Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/docs/guide/using-with-android.md @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
1 # Using with Android
2
3 ## Introduction
4
5 This document outlines the steps necessary to use the MuPDF Android Library in various ways.
6
7 First, we show you how to embed MuPDF in your app. Then, we explain how to
8 customize the viewer if you need to change how it looks or behaves. Finally, we
9 tell you where to go if you need to do work on the library itself.
10
11 Embedding the viewer in your app provides an activity that you can start to
12 view PDF documents from within your app. This should be enough for most use
13 cases.
14
15 ## Acquire a valid license
16
17 ### Open Source license
18
19 If your software is open source, you may use MuPDF under the terms of the
20 [GNU Affero General Public License](https://www.gnu.org/licenses/agpl-3.0.html).
21
22 This means that *all of the source code* for your *complete* app must be
23 released under a compatible open source license!
24
25 It also means that you may *not* use any proprietary closed source libraries or
26 components in your app. This includes (but is not limited to):
27
28 - Google Play Services
29 - Google Mobile Services
30 - AdMob by Google
31 - Crashlytics
32 - Answers
33 - *etc.*
34
35 Just because a library ships with Android or is made by Google does *not* make it AGPL compatible!
36
37 If you cannot or do not want to comply with these restrictions, you **must** acquire a commercial license instead.
38
39 ### Commercial license
40
41 If your software is not open source, Artifex Software can sell you a license to use MuPDF in closed source software.
42
43 Fill out the
44 [MuPDF product inquiry form](https://artifex.com/contact/mupdf-inquiry.php?utm_source=rtd-mupdf&utm_medium=rtd&utm_content=inline-link)
45 for commercial licensing terms and pricing.
46
47 ## Add the MuPDF Library to your project
48
49 The MuPDF library uses the Gradle build system.
50 In order to include MuPDF in your app, you also need to use Gradle.
51 The Eclipse and Ant build systems are not supported.
52
53 The MuPDF library needs Android version 4.1 or newer.
54 Make sure that the `minSdkVersion` in your app's `build.gradle` is at least 16.
55
56 android {
57 defaultConfig {
58 minSdkVersion 16
59 ...
60 }
61 ...
62 }
63
64 The MuPDF library can be retrieved as a pre-built artifact from our Maven repository.
65 In your project's top `build.gradle`, add the line to the repositories section:
66
67 allprojects {
68 repositories {
69 jcenter()
70 maven { url 'http://maven.ghostscript.com' }
71 ...
72 }
73 }
74
75 Then add the MuPDF viewer library to your app's dependencies.
76 In your app's `build.gradle`, add the line to the dependencies section:
77
78 dependencies {
79 api 'com.artifex.mupdf:viewer:1.15.+'
80 ...
81 }
82
83 ## Invoke the document viewer activity
84
85 Once this has been done, you have access to the MuPDF viewer activity.
86 You can now open a document viewing activity by launching an `Intent`,
87 passing the URI of the document you wish to view.
88
89 import com.artifex.mupdf.viewer.DocumentActivity;
90
91 public void startMuPDFActivity(Uri documentUri) {
92 Intent intent = new Intent(this, DocumentActivity.class);
93 intent.setAction(Intent.ACTION_VIEW);
94 intent.setData(documentUri);
95 startActivity(intent);
96 }
97
98 ## How to customize the viewer
99
100 If you've already tried embedding the viewer in your app, but are unhappy with some
101 aspect of the look or behavior and want to modify it in some way, this section should
102 point you in the right direction.
103
104 ### Decide which viewer to base your customizations on
105
106 In order to customize the viewer UI, you will need to modify the existing Android viewer activity.
107 There are two separate code bases you can start with:
108
109 - `mupdf-android-viewer`
110 The main viewer app. This code is difficult to work with, but has the most
111 features and pre-renders neighboring pages into a page cache for faster page
112 turning performance.
113
114 - `mupdf-android-viewer-mini`
115 This is a minimalist viewer which has fewer features but is designed to be
116 easy to understand and modify. It does not (currently) have high-resolution
117 zooming, and it does not use the swipe gesture to flip pages (it requires the
118 user to tap on the side of the screen to flip pages).
119
120 If all you want to do is brand the UI with your own colors and icons, you are
121 welcome to use whichever code base you prefer. However, if you want to do
122 extensive modifications, we suggest you base your code on the mini viewer.
123
124 ### Check out the chosen project
125
126 When you have decided which project to base your modifications on, you should check out
127 the corresponding git repository:
128
129 $ git clone git://git.ghostscript.com/mupdf-android-viewer.git
130 $ git clone git://git.ghostscript.com/mupdf-android-viewer-mini.git
131
132 Inside the checked out project you will find two modules: `app` and `lib`.
133 The `app` module is a file chooser activity that lets the user open files from the external storage.
134 The `lib` module is the viewer activity, which provides the `com.artifex.mupdf:viewer`
135 package that you're already using.
136
137 The `lib` module is the one you want; ignore everything else in this project.
138
139 ### Copy the viewer library module into your project
140
141 Copy the 'lib' directory to your project, renaming it to something appropriate.
142 The following instructions assume you called the directory 'mupdf-lib'.
143
144 Don't forget to include the module in the `settings.gradle` file:
145
146 include ':app'
147 include ':mupdf-lib'
148 ...
149
150 You'll also want to change your app's dependencies to now depend on your local
151 copy rather than the official MuPDF viewer package. In your app `build.gradle`:
152
153 dependencies {
154 api project(':mupdf-lib')
155 ...
156 }
157
158 The `lib` module depends on the JNI library `com.artifex.mupdf:fitz`, so do
159 *not* remove the Maven repository from your top `build.gradle`.
160
161 ### Edit the viewer activity
162
163 If all has gone well, you can now build your project with the local viewer library,
164 and access the MuPDF viewer activity just as you used to.
165
166 You're now free to customize the resources in `mupdf-lib/src/main/res` and behavior in
167 `mupdf-lib/src/main/java` as you desire.
168
169 ## Working on the MuPDF Library
170
171 If you want to work on the library itself, rather than just use it, you will need
172 to check out the following git repositories.
173
174 - `mupdf.git`
175 This repository contains the low-level "fitz" C library and the JNI bindings.
176
177 - `mupdf-android-fitz.git`
178 This repository contains an Android project to build the C library and JNI bindings.
179 It uses `mupdf.git` as a Git submodule.
180
181 - `mupdf-android-viewer.git`
182 This repository contains the Android viewer library and app.
183 It uses `mupdf-android-fitz.git` as either a Maven artifact or Git submodule.
184
185 - `mupdf-android-viewer-mini.git`
186 This repository contains the minimalist Android viewer library and app.
187 It uses `mupdf-android-fitz.git` as either a Maven artifact or Git submodule.
188
189 These repositories are set up with Git submodules. If you're a Git expert,
190 you can clone one of the viewer repositories recursively and get the fitz
191 and mupdf git repositories all at once.
192
193 If you only want to work with one of the viewer repositories, you can clone it
194 non-recursively and use the Maven artifact for the JNI bindings library and not
195 worry about the `mupdf.git` and `mupdf-android-fitz.git` repositories.