diff options
Diffstat (limited to 'docs/android-sdk.html')
-rw-r--r-- | docs/android-sdk.html | 330 |
1 files changed, 330 insertions, 0 deletions
diff --git a/docs/android-sdk.html b/docs/android-sdk.html new file mode 100644 index 00000000..d48a33af --- /dev/null +++ b/docs/android-sdk.html @@ -0,0 +1,330 @@ +<!DOCTYPE html> +<html> +<head> +<title>MuPDF Android SDK</title> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +<style> +body {counter-reset: h2} +h2 {counter-reset: h3} +h3 {counter-reset: h4} +h4 {counter-reset: h5} +h5 {counter-reset: h6} +h2:before {counter-increment: h2; content: counter(h2) ". "} +h3:before {counter-increment: h3; content: counter(h2) "." counter(h3) ". "} +h4:before {counter-increment: h4; content: counter(h2) "." counter(h3) "." counter(h4) ". "} +h5:before {counter-increment: h5; content: counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) ". "} +h6:before {counter-increment: h6; content: counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) "." counter(h6) ". "} +</style> +</head> + +<body> + +<header> +<h1>MuPDF Android SDK</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">About</a> +<a href="http://mupdf.com/news.html">News</a> +<a href="index.html">Documentation</a> +<a href="http://mupdf.com/downloads/">Downloads</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">Source</a> +<a href="https://bugs.ghostscript.com/">Bugs</a> +</nav> + +<article> + +<p> +This document outlines the steps necessary to use the MuPDF Android SDK in various ways. + +<p> +First, we show you how to embed the SDK in your app. Then, we explain how to +customize the viewer if you need to change how it looks or behaves. Finally, we +tell you where to go if you need to do work on the SDK itself. + +<p> +Embedding the viewer in your app provides an activity that you can start to +view PDF documents from within your app. This should be enough for most use +cases. + +<h2 id="acquire-license"> +Acquire a valid license +</h2> + +<p> +Before using MuPDF, please make sure that you have a valid license to do so. +There are two available licenses; make sure you pick the one whose terms you can comply with. + +<h3> +Open Source license +</h3> + +<p> +If your software is open source, you may use MuPDF under the terms of the +<a href="https://www.gnu.org/licenses/agpl-3.0.html">GNU Affero General Public License</a>. + +<p> +This means that <i>all of the source code</i> for your <i>complete</i> app must be +released under a compatible open source license! + +<p> +It also means that you may <i>not</i> use any proprietary closed source libraries or +components in your app. This includes (but is not limited to) + Google Play Services, + Google Mobile Services, + AdMob by Google, + Crashlytics, + Answers, + etc. + +<p> +Just because a library ships with Android or is made by Google does <i>not</i> make it AGPL compatible! + + +<p> +If you cannot or do not want to comply with these restrictions, +you <i><b>must</b></i> acquire a commercial license instead. + +<h3> +Commercial license +</h3> + +<p> +If your software is not open source, Artifex Software can sell you a license to use MuPDF in closed source software. +Go and fill out the <a href="http://artifex.com/contact-us/">product inquiry form</a> +for commercial licensing terms and pricing. + +<h2 id="setup-build"> +Add the MuPDF SDK to your project +</h2> + +<p> +The MuPDF library uses the Gradle build system. +In order to include MuPDF in your app, you also need to use Gradle. +The Eclipse and Ant build systems are not supported. + +<p> +The MuPDF library needs Android version 4.1 or newer. +Make sure that the minSdkVersion in your app's build.gradle is at least 16. + +<pre> +android { + defaultConfig { + <b>minSdkVersion 16</b> + ... + } + ... +} +</pre> + +<p> +The MuPDF library can be retrieved as a pre-built artifact from our Maven repository. +Add the maven repository to your project. In your project's top build.gradle, add the bolded line to +to the repositories section: + +<pre> +allprojects { + repositories { + jcenter() + <b>maven { url 'http://maven.ghostscript.com' }</b> + ... + } +} +</pre> + +<p> +Then add the MuPDF viewer library to your app's dependencies. +In your app's build.gradle, add the bolded line to the dependencies section: + +<pre> +dependencies { + <b>compile 'com.artifex.mupdf:viewer:1.11.+'</b> + ... +} +</pre> + +<h2 id="use-activity"> +Invoke the document viewer activity +</h2> + +<p> +Once this has been done, you have access to the MuPDF viewer activity. +You can now open a document viewing activity by launching an intent, +passing the URI of the document you wish to view. + +<pre> +import com.artifex.mupdf.viewer.DocumentActivity; + +public void startMuPDFActivity(Uri documentUri) { + Intent intent = new Intent(this, DocumentActivity.class); + intent.setAction(Intent.ACTION_VIEW); + intent.setData(documentUri); + startActivity(intent); +} +</pre> + +<p> +The activity supports viewing both file and content scheme URIs. + +<p> +For example, to open the PDF file in ~/Download/example.pdf: + +<pre> +public void startMuPDFActivityWithExampleFile() { + File dir = Environment.getExternalStoragePublicDirectory + (Environment.DIRECTORY_DOWNLOADS); + File file = new File(dir, "example.pdf") + Uri uri = Uri.fromFile(file); + startMuPDFActivity(uri); +} +</pre> + +<h2> +How to customize the viewer +</h2> + +<p> +If you've already tried embedding the viewer in your app, but are unhappy with some +aspect of the look or behavior and want to modify it in some way, this document should +point you in the right direction. + +<h3> +Decide which viewer to base your customizations on +</h3> + +<p> +In order to customize the viewer UI, you will need to modify the existing android viewer activity. +There are two separate code bases you can start with: + +<dl> +<dt>mupdf-android-viewer: +<dd>The main viewer app. This code is difficult to work with, but has the most +features and pre-renders neighboring pages into a page cache for faster page +turning performance. +<dt>mupdf-android-viewer-mini: +<dd>This is a minimalist viewer which has fewer features but is designed to be +easy to understand and modify. It does not (currently) have high-resolution +zooming, and it does not use the swipe gesture to flip pages (it requires the +user to tap on the side of the screen to flip pages). +</dl> + +<p> +If all you want to do is brand the UI with your own colors and icons, you are +welcome to use whichever code base you prefer. However, if you want to do +extensive modifications, we suggest you base your code on the mini viewer. + +<h3> +Check out the chosen project +</h3> + +<p> +When you have decided which project to base your modifications on, you should check out +the corresponding git repository: + +<pre> +$ git clone git://git.ghostscript.com/mupdf-android-viewer.git +$ git clone git://git.ghostscript.com/mupdf-android-viewer-mini.git +</pre> + +<p> +Inside the checked out project you will find two modules: app and lib. +The app module is a file chooser activity that lets the user open files from the external storage. +The lib module is the viewer activity, which provides the "com.artifex.mupdf:viewer" +package that you're already using. + +<p> +The lib module is the one you want; ignore everything else in this project. + +<h3> +Copy the viewer library module into your project +</h3> + +<p> +Copy the 'lib' directory to your project, renaming it to something appropriate. +The following instructions assume you called the directory 'mupdf-lib'. +Don't forget to include the module in the settings.gradle file: + +<pre> +include ':app' +<b>include ':mupdf-lib'</b> +... +</pre> + +<p> +You'll also want to change your app's dependencies to now depend on your local +copy rather than the official mupdf viewer package. In your app build.gradle: + +<pre> +dependencies { + <strike>compile 'com.artifex.mupdf:viewer:1.11.+'</strike> + <b>compile project(':mupdf-lib')</b> + ... +} +</pre> + +<p> +The lib module depends on the JNI library "com.artifex.mupdf:fitz", so do +<i>not</i> remove the maven repository from your top build.gradle. + +<h3> +Edit the viewer activity +</h3> + +<p> +If all has gone well, you can now build your project with the local viewer library, +and access the mupdf viewer activity just as you used to. + +<p> +You're now free to customize the resources in mupdf-lib/src/main/res and behavior in +mupdf-lib/src/main/java as you desire. + +<h2> +Working on the MuPDF SDK +</h2> + +<p> +If you want to work on the SDK itself, rather than just use it, you will need +to check out the following git repositories. + +<dl> +<dt>mupdf.git +<dd>This repository contains the low-level "fitz" C library and the JNI bindings. +<dt>mupdf-android-fitz.git +<dd>This repository contains an Android project to build the C library and JNI bindings. +It uses mupdf.git as a git submodule. +<dt>mupdf-android-viewer.git +<dd>This repository contains the Android viewer library and app. +It uses mupdf-android-fitz.git as either a Maven artifact or git submodule. +<dt>mupdf-android-viewer-mini.git +<dd>This repository contains the minimalist Android viewer library and app. +It uses mupdf-android-fitz.git as either a Maven artifact or git submodule. +<dt>mupdf-android-viewer-old.git +<dd>This repository contains the old Android viewer. It has its own JNI +bindings and uses mupdf.git as a submodule directly. It is only listed here for +completeness sake, and is not part of the SDK. +</dl> + +<p> +Since these repositories are set up as git submodules, if you're a Git expert, +you can clone one of the viewer repositories recursively and get all of them at +once. However, working with git submodules can be fraught with danger, so it +may be easier to check them out individually. + +<p> +If you only want to work with one of the viewer repositories, you can use the +Maven artifact for the JNI bindings library and not worry about the mupdf.git +and mupdf-android-fitz.git repositories. + +<p> +Good luck! + +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> + +</body> +</html> |