A4 PDF Reader
You will design and implement a PDF reader that allows a user to read and annotate a document on an Android tablet.
Design and implement a mobile PDF reader on Android. The screen should look something like this. Note that you have license to change the layout and appearance, as long as you support all of the features and functionality described below.
When first launched, the application will load a sample PDF that you have included in your project. The titlebar should show the name of the PDF. The statusbar should show the current page number and the total number of pages (e.g. “page 2/5”).
You need to support the following functionality. Unless a feature specifically states how you should activate it, you can choose how to present these to the user. e.g. either back/forward buttons, or swipe left/right could be used to switch pages. Make sure to document in the README how to use your features.
- Navigate: Browse forward and backwards through the pages in the document. The status bar should update to indicate the current page.
- Drawing: The user can draw on the current page, allowing them to write notes or draw on a page. The user cannot change the color or thickness of the line, so default to color and thickness that are easy to read and support writing on a page.
- Highlighting: The user can draw over the existing document with a thick, transparent yellow brush that allows the user to highlight the text in the PDF. Make sure that the highlighter is transparent enough that the text beneath it remains visible! See the diagram above for an example.
- Erase: The user should be able to erase an existing drawing or highlighting.
- Zoom & Pan: The user can use two fingers to zoom-in and zoom-out (by bringing their fingers closer together or spreading them apart over the area of interest). When zoomed-in, users can pan around to reposition the document. These gestures should behave the same as standard pan-and-zoom (hint: try Google Maps on the emulator to see how these gestures should work). Users can draw and highlight a document at any scale, and the annotations should scale with the document canvas.
- Undo/Redo: Undo the last change that was made to the document. The user should be able to undo at least the last 5 actions that were performed. Redo can be used to revert the undo (as described in class).
Any gestures that you implement (e.g. zoom, pan, possible moving between pages) should respect direct manipulation principles. For instance, content should remain under your finger as you zoom or pan. Gestures should also follow principles discussed in class (e.g. given design principles, swipe-back would be a good choice for navigating to the previous page, but a poor choice for the erase tool).
NEW: It can be difficult to get some gestures working on the emulator; two-finger panning in particular is awkward and not reliable. You must implement two-finger zooming, but you are allowed some flexibility with the other gestures. For example, you can:
- use two-fingers to zoom or pan, and one-finger to draw.
- use two-fingers for zoom, but have buttons that let you toggle between draw and pan modes, using one-finger for both (i.e. modal).
In both cases, you would still be expected to pan by touching and dragging.
You should handle orientation changes in your application, so the application remains usable in either portrait or landscape mode. Rotating the device should not result in data loss. When you change orientation, the document can scale to the width of the screen (i.e. snap-to-width), or reset - your choice on how it behaves.
You should support multi-page PDFs, and your sample document needs to have at least 3 pages.
You should save changes when the user changes pages, or exits. A user should be able to make changes, exit your applicaton, and then reload it and see their changes intact. Drawing and highlighting should be saved on each page i.e. it should not be lost when the user navigates between pages.
You are provided starter code that loads a sample PDF and logs touch events. You are free to use this code, or ignore it and implement everything your own way (but using this code will likely save you some time!).
- IMPORTANT: If you are using IntelliJ IDEA, use this project instead which supports the correct version of the Android plugin for that environment. The code is the same aside from that config change.
You must create this assignment as an Android project using the Android API 30 SDK. Note: this is the minimum version that you should use. You are welcome to install and run newer versions if you wish.
For development and testing, use a Pixel C tablet AVD with API 30 or later. Document the API level in your README file.
You can use any functionality included in the Android SDK, and are free to use code snippets from the Android sample code included with the SDK (i.e. a snippet being a small segment of code). You can also use any code that we have placed in the public CS 349 Git repo. If you do this, put comments in your code referencing the original source. You are not allowed to use any other third-party code or libraries, unless you obtain permission from the instructor.
Your directory structure for your assignment submission should be in subdirectories under your a4/ directory in your Git repository. It should use a standard Gradle layout for an Android project.
Your submission needs to include:
- All source code and resources required to build and execute your program.
- A Gradle project that compiles everything in IntelliJ using the specified JDK and Android SDK, and which has a Run target that will execute your program.
- A `readme.md’ file with any details required to help the TA grade your assignment.
- An APK file at the top-level of your directory structure. You will likely need to manually create this (Build -> Build APK) and copy to this location. This will help the TA to load and test your application without needing to load the project.
Your readme file needs to include, at a minimum, your name, student number, the version of the Android SDK that you used, and details on your AVD. If the TA needs to know anything else to run your assignment (e.g. undocumented hotkeys), include them in this file.
Late assignments will not be accepted. Markers will test your application by running your APK file against the appropriate AVD. Your submission will be assessed roughly as follows:
- 5%. Code compiles and runs properly. Includes README, APK file.
- 10%. PDF is displayed and the user can navigate through pages.
- 5%. The title bar shows the name of the PDF, status bar shows page number/total pages.
- 20%. User can annotate the PDF using either the pen or the highlighter tools.
- 10%. User can erase an annotation using the erase tool.
- 10%. User can undo/redo at least 5 levels of actions that they perform.
- 20%. User can zoom and pan using standing gestures. Annotations scale with the canvas.
- 10%. Rotating the device will change orientation (landscape or portrait).
- 5%. Data persists when the user navigates between pages, or changes orientation.
- 5%. User controls are obvious/clear and intuitive, and support the features required.
- July 9, 2023. Initial draft.
- July 26, 2023. Added clarification on panning.