1 /*
2  * Copyright (C) 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 android.graphics.pdf.models.selection;
18 
19 import android.annotation.FlaggedApi;
20 import android.annotation.NonNull;
21 import android.graphics.pdf.content.PdfPageTextContent;
22 import android.graphics.pdf.flags.Flags;
23 import android.graphics.pdf.utils.Preconditions;
24 import android.os.Parcel;
25 import android.os.Parcelable;
26 
27 import java.util.List;
28 
29 /**
30  * <p>
31  * Represents the list of selected content on a particular page of the PDF document. By
32  * default, the selection boundary is represented from left to right.
33  * <strong>Note: </strong>Currently supports text selection only.
34  */
35 @FlaggedApi(Flags.FLAG_ENABLE_PDF_VIEWER)
36 public final class PageSelection implements Parcelable {
37     @NonNull
38     public static final Creator<PageSelection> CREATOR = new Creator<PageSelection>() {
39         @Override
40         public PageSelection createFromParcel(Parcel in) {
41             return new PageSelection(in);
42         }
43 
44         @Override
45         public PageSelection[] newArray(int size) {
46             return new PageSelection[size];
47         }
48     };
49 
50     private final int mPage;
51     private final SelectionBoundary mStart;
52     private final SelectionBoundary mStop;
53     private final List<PdfPageTextContent> mSelectedContents;
54 
55     /**
56      * Creates a new instance of {@link PageSelection} for the specified page, the start and stop
57      * selection boundary, and the selected text content.
58      *
59      * @param page             The page number of the selection.
60      * @param start            Boundary where the selection starts.
61      * @param stop             Boundary where the selection stops.
62      * @param selectedContents list of segments of selected text content.
63      * @throws IllegalArgumentException If the page number is negative.
64      * @throws NullPointerException     If start/stop edge or text selection is null.
65      */
PageSelection(int page, @NonNull SelectionBoundary start, @NonNull SelectionBoundary stop, @NonNull List<PdfPageTextContent> selectedContents)66     public PageSelection(int page, @NonNull SelectionBoundary start,
67             @NonNull SelectionBoundary stop, @NonNull List<PdfPageTextContent> selectedContents) {
68         Preconditions.checkArgument(page >= 0, "Page number cannot be negative");
69         Preconditions.checkNotNull(start, "Start boundary cannot be null");
70         Preconditions.checkNotNull(stop, "Stop boundary cannot be null");
71         Preconditions.checkNotNull(selectedContents, "Selected text content " + "cannot be null");
72         this.mStart = start;
73         this.mStop = stop;
74         this.mPage = page;
75         this.mSelectedContents = selectedContents;
76     }
77 
PageSelection(Parcel in)78     private PageSelection(Parcel in) {
79         mPage = in.readInt();
80         mStart = in.readParcelable(SelectionBoundary.class.getClassLoader());
81         mStop = in.readParcelable(SelectionBoundary.class.getClassLoader());
82         mSelectedContents = in.createTypedArrayList(PdfPageTextContent.CREATOR);
83     }
84 
85     /**
86      * Gets the particular page for which the selection is highlighted.
87      *
88      * @return The page number on which the current selection resides.
89      */
getPage()90     public int getPage() {
91         return mPage;
92     }
93 
94     /**
95      * <p>
96      * Gets the edge from where the selection starts- index is inclusive.
97      *
98      * @return The starting edge of the selection.
99      */
100     @NonNull
getStart()101     public SelectionBoundary getStart() {
102         return mStart;
103     }
104 
105     /**
106      * <p>
107      * Gets the edge where the selection stops - index is inclusive.
108      *
109      * @return The stopping edge of the selection.
110      */
111     @NonNull
getStop()112     public SelectionBoundary getStop() {
113         return mStop;
114     }
115 
116     /**
117      * Returns the text content within the selection boundaries on the page. In case there are
118      * non-continuous selections, this method returns the list of those text content in order of
119      * viewing.
120      *
121      * @return list of text contents within the selection boundaries.
122      */
123     @NonNull
getSelectedTextContents()124     public List<PdfPageTextContent> getSelectedTextContents() {
125         return mSelectedContents;
126     }
127 
128     @Override
describeContents()129     public int describeContents() {
130         return 0;
131     }
132 
133     @Override
writeToParcel(@ndroidx.annotation.NonNull Parcel dest, int flags)134     public void writeToParcel(@androidx.annotation.NonNull Parcel dest, int flags) {
135         dest.writeInt(mPage);
136         dest.writeParcelable(mStart, flags);
137         dest.writeParcelable(mStop, flags);
138         dest.writeTypedList(mSelectedContents);
139     }
140 }
141