1 /*
2  * Copyright 2024 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package androidx.pdf
18 
19 import android.graphics.Bitmap
20 import android.graphics.PointF
21 import android.graphics.Rect
22 import android.net.Uri
23 import android.util.Size
24 import android.util.SparseArray
25 import androidx.annotation.RestrictTo
26 import androidx.pdf.content.PageMatchBounds
27 import androidx.pdf.content.PageSelection
28 import androidx.pdf.content.PdfPageGotoLinkContent
29 import androidx.pdf.content.PdfPageImageContent
30 import androidx.pdf.content.PdfPageLinkContent
31 import androidx.pdf.content.PdfPageTextContent
32 import java.io.Closeable
33 
34 @RestrictTo(RestrictTo.Scope.LIBRARY)
35 /** Represents a PDF document and provides methods to interact with its content. */
36 public interface PdfDocument : Closeable {
37 
38     /** The URI of the document represented by this object */
39     public val uri: Uri
40 
41     /** The total number of pages in the document. */
42     public val pageCount: Int
43 
44     /** Indicates whether the document is linearized (optimized for fast web viewing). */
45     public val isLinearized: Boolean
46 
47     /** The type of form present in the document. */
48     public val formType: Int
49 
50     /**
51      * Asynchronously retrieves information about the specified page.
52      *
53      * @param pageNumber The page number (0-based).
54      * @return A [PageInfo] object containing information about the page.
55      */
getPageInfonull56     public suspend fun getPageInfo(pageNumber: Int): PageInfo
57 
58     /**
59      * Asynchronously retrieves information about a range of pages.
60      *
61      * @param pageRange The range of page numbers (0-based, inclusive).
62      * @return A list of [PageInfo] objects, one for each page in the range.
63      */
64     public suspend fun getPageInfos(pageRange: IntRange): List<PageInfo>
65 
66     /**
67      * Asynchronously searches the document for the specified query within a range of pages.
68      *
69      * @param query The search query string.
70      * @param pageRange The range of page numbers (0-based, inclusive) to search within.
71      * @return A [SparseArray] mapping page numbers to lists of [PageMatchBounds] objects
72      *   representing the search results on each page.
73      */
74     public suspend fun searchDocument(
75         query: String,
76         pageRange: IntRange
77     ): SparseArray<List<PageMatchBounds>>
78 
79     /**
80      * Asynchronously retrieves the selection bounds (in PDF coordinates) for the specified text
81      * selection.
82      *
83      * @param pageNumber The page on which text to be selected.
84      * @param start The starting point of the text selection.
85      * @param stop The ending point of the text selection.
86      * @return A [PageSelection] object representing the selection bounds on the page.
87      */
88     public suspend fun getSelectionBounds(
89         pageNumber: Int,
90         start: PointF,
91         stop: PointF
92     ): PageSelection?
93 
94     /**
95      * Asynchronously retrieves the selection bounds (in PDF coordinates) for the complete text on
96      * the page.
97      *
98      * @param pageNumber The page on which text to be selected.
99      * @return A [PageSelection] object representing the selection bounds on the page.
100      */
101     @RestrictTo(RestrictTo.Scope.LIBRARY)
102     public suspend fun getSelectAllSelectionBounds(
103         pageNumber: Int,
104     ): PageSelection?
105 
106     /**
107      * Asynchronously retrieves the content (text and images) of the specified page.
108      *
109      * @param pageNumber The page number (0-based).
110      * @return A [PdfPageContent] object representing the page's content.
111      */
112     public suspend fun getPageContent(pageNumber: Int): PdfPageContent?
113 
114     /**
115      * Asynchronously retrieves the links (Go To and external) present on the specified page.
116      *
117      * @param pageNumber The page number (0-based).
118      * @return A [PdfPageLinks] object representing the page's links.
119      */
120     public suspend fun getPageLinks(pageNumber: Int): PdfPageLinks
121 
122     /**
123      * Gets a [BitmapSource] for retrieving bitmap representations of the specified page.
124      *
125      * @param pageNumber The page number (0-based).
126      * @return A [BitmapSource] for the specified page, or null if the page number is invalid.
127      */
128     public fun getPageBitmapSource(pageNumber: Int): BitmapSource
129 
130     /**
131      * Represents information about a single page in the PDF document.
132      *
133      * @property pageNum The page number (0-based).
134      * @property height The height of the page in points.
135      * @property width The width of the page in points.
136      */
137     public class PageInfo(public val pageNum: Int, public val height: Int, public val width: Int)
138 
139     /** A source for retrieving bitmap representations of PDF pages. */
140     public interface BitmapSource : Closeable {
141         public val pageNumber: Int
142 
143         /**
144          * Asynchronously retrieves a bitmap representation of the page, optionally constrained to a
145          * specific tile region.
146          *
147          * @param scaledPageSizePx The scaled page size in pixels, representing the page size in
148          *   case of no zoom, and scaled page size in case of zooming.
149          * @param tileRegion (Optional) The region of the page to include in the bitmap, in pixels
150          *   within the `scaledPageSizePx`. This identifies the tile. If null, the entire page is
151          *   included.
152          * @return The bitmap representation of the page.
153          */
154         public suspend fun getBitmap(scaledPageSizePx: Size, tileRegion: Rect? = null): Bitmap
155     }
156 
157     /**
158      * Represents the combined text and image content within a single page of a PDF document.
159      *
160      * @property textContents A list of [PdfPageTextContent] objects representing the text elements
161      *   on the page.
162      * @property imageContents A list of ]PdfPageImageContent] objects representing the image
163      *   elements on the page.
164      */
165     public class PdfPageContent(
166         public val textContents: List<PdfPageTextContent>,
167         public val imageContents: List<PdfPageImageContent>
168     )
169 
170     /**
171      * Represents the links within a single page of a PDF document.
172      *
173      * @property gotoLinks A list of internal links (links to other pages within the same document)
174      *   represented as [PdfPageGotoLinkContent] objects.
175      * @property externalLinks A list of external links (links to web pages or other resources)
176      *   represented as [PdfPageLinkContent] objects.
177      */
178     public class PdfPageLinks(
179         public val gotoLinks: List<PdfPageGotoLinkContent>,
180         public val externalLinks: List<PdfPageLinkContent>
181     )
182 
183     /**
184      * Represents a point within a specific page of a PDF document.
185      *
186      * @property pageNumber The page number (0-based) where the point is located.
187      * @property pagePoint The coordinates (x, y) of the point relative to the page's origin.
188      */
189     public class PdfPoint(public val pageNumber: Int, public val pagePoint: PointF)
190 }
191