1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
|
<!DOCTYPE html>
<html>
<head>
<title>MuPDF Android SDK</title>
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body>
<header>
<h1>MuPDF Android SDK</h1>
</header>
<article>
<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>
<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="https://www.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>api 'com.artifex.mupdf:viewer:1.15.+'</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>api 'com.artifex.mupdf:viewer:1.15.+'</strike>
<b>api 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://www.artifex.com/"><img src="artifex-logo.png" align="right"></a>
Copyright © 2006-2019 Artifex Software Inc.
</footer>
</body>
</html>
|
