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.phoenix.DefaultUIActivity
import com.artifex.solib.ArDkLib
import com.artifex.solib.ConfigOptions

...

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

// Setup the document viewing configuration options
val appCfgOpts = ConfigOptions()
ArDkLib.setAppConfigOptions(appCfgOpts)

startActivity(defaultUI)

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 with 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.

Starting a Document View#

Initializing the document view#

On the Activity which you want to use to display the document you are required to setup the DocumentView class within the onCreate method as follows:

//  this needs to be done before calling super.onCreate
DocumentView.initialize(this)

Presenting the document#

You should have an area of your UI dedicated to display the document defined in your corresponding activity’s layout XML file (as an example this could be a constraint based layout called “document_view_holder”). Next we need to instantiate our DocumentView, add it to our layout and finally start the DocumentView.

The following code assumes have you have obtained a valid document uri:

// create a DocumentView for our document type
val filename = FileUtils.filenameFromUri(this, documentUri)
val documentView:DocumentView = DocumentView.create(this, filename)

// add it to our layout
val parent = findViewById<ViewGroup>(R.id.document_view_holder)
parent.addView(documentView,
    RelativeLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT,
                                ViewGroup.LayoutParams.MATCH_PARENT))

documentView.setDocConfigOptions(ArDkLib.getAppConfigOptions())
documentView.setDocDataLeakHandler(Utilities.getDataLeakHandlers())

// open it, specifying showUI = false;
documentView.start(documentUri, 0, false)

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 Default UI on top of the document view or not - for the Custom UI this should always be set to 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, USA, for further information.Discord logo