CMPT 381 Assignment 4

Digital Ink, Grouping, Transforms, Cut/Copy/Paste

Due: Tuesday, April 7, 11:59pm (handin closes Thursday, April 9, 11:59pm)

Overview

In this assignment you will build an interactive Android application for creating and manipulating lines. The lines are drawn freehand as digital ink and are converted to straight lines if the ink is a reasonable approximation of a line. Users can select lines and adjust the endpoints, and endpoints snap to the endpoints of other lines. A selected line can be scaled or rotated using sliders. A selected set of lines can be grouped, and then scaled or rotated as a group. Selections can be cut, copied, and pasted using the app’s menu.

Part 1: App basics and digital ink

Use the Android Studio IDE to develop an app named LineSketch with the following properties:

 Minimum API level: 26 (Android 8.0)
 Create the app as an “Empty Activity” in the setup wizard
 Project name: LineSketch
 Language: Java

Your app will have the following components:

 A main activity (SketchMainActivity)
 A main view for drawing the lines (SketchView)
 A slider for rotating selected objects or groups (see 2B below)
 A slider for scaling selected objects or groups (see 2B below)
 A menu that has five menu items: Cut, Copy, Paste, Group, Ungroup
 An MVC architecture including an interaction model and a state machine for your controller (classes SketchModel, Line,
SketchView, SketchController, and InteractionModel; and interface SketchListener)

Notes:

 The app will be run on the Android emulator, using a Pixel 2 profile running API level 26 or later.
 No physical device is needed
 The app will only be run in portrait mode; you do not have to handle orientation changes.

Part 1A: Layout container, menu, and Sliders

Software Requirements:

 Create a vertical linear layout container to hold two sliders and the custom view (see 1B)
 Sliders in Android use the SeekBar widget: developer.android.com/reference/android/widget/SeekBar.html
 Create the sliders, set up their event handlers, and add them to the layout in your main activity
 Events for SeekBars are handled by an onSeekBarChangeListener, which should be your main activity class (for reasons we
will discuss in class); the listener methods should then call your controller with the slider values
 Create the menu using a similar technique to that used for Assignment 3
 Put the onCreateOptionsMenu and onOptionsItemSelected methods in your main activity class

Part 1B: Custom View for drawing with digital ink

Create a custom View class using similar techniques to that used for Assignment 3.

Interaction Requirements:

 When the user moves their finger on the view, all touch points are recorded and drawn as digital ink
 When the user lifts their finger, the current ink stroke is evaluated to see whether it can be converted to a straight line
o The straight line must start at the first ink point and end at the last ink point
o Your system must determine whether the ink points are close enough to a line to be converted
o If the ink is determined to be close enough to a line, a new Line object is added to the model
o If the ink is not close enough to a line, no line is drawn
o In either case, the ink points are discarded once the user’s finger is lifted
 In the SketchView class, digital ink should be drawn in grey, and the Lines should be drawn in green (until selected, as
discussed below)

Software Requirements:

 Store information about the digital ink (e.g., the collection of points) in the InteractionModel
 To draw the ink, you can either connect the points or use Android’s Path class:
https://developer.android.com/reference/android/graphics/Path

Resources for Part 1:

 Basic Android and IDE resources are linked to the course moodle
 Custom drawing tutorial for Android: https://developer.android.com/training/custom-views/custom-drawing
 Example code for basic MVC architecture and custom drawing in Android are on the course moodle
 General discussion of digital ink: Olsen Chapter 19

When you are finished Part 1:

 Take a snapshot of your project using Android Studio’s “File  Export to Zip file” menu command
o Rename this zipfile “381-A4-Part1.zip”
 You will hand in this zip to show that you have successfully completed Part 1

Part 2: Single selection and transformations

Part 2A: Single selection and translation

Interaction Requirements:

 When the user touches on a line, the line should be selected
o There should be a “close enough” threshold of 20 pixels on either side of the line, so that the user does not need
to be exactly on the line to select it
o If the user touches between two lines and both are within the threshold, any line can be selected
o Selection is shown by drawing the line in yellow, and by showing selection handles on the endpoints
o Selection is persistent; deselecting is done by tapping on the background (down+up without moving)
 If the user starts drawing a new line, any selection is deselected
 If the user touches a selected line and then moves their touch point, the line is translated
o If the user touches an unselected line and then moves, nothing happens
 If the user selects a line and then touches and drags on an endpoint, that endpoint is moved with the finger
o If the endpoint is released within the threshold of another endpoint, it should snap to that endpoint
o If the endpoint is released within range of two endpoints, it can snap to either one

Software Requirements:

 Add states to your controller state diagram, and code to your controller class, to handle the new interactions (selecting,
dragging, and endpoint movement)
 Add code to your controller and model classes to snap the line endpoints
 Lines are drawn in green by the SketchView class (set the stroke width to 10)
o Also draw a semi-transparent wider line to indicate the selectable region; set this stroke width to twice your close-
enough threshold
 Line endpoint handles should be implemented as part of the Line class
 You should not store a line’s coordinates as “home coordinates”; you should store them as view coordinates (i.e., pixels).
(Reasons for this will be discussed in lectures, but in brief, it will make some operations easier later on)

Resources for Part 2A:

 Example code for transforms (in JavaFX) is on the moodle (FXTransformsDemo.zip)
 Example code for the “distance to line” operation, to be added to the Line class:

Given a line with two endpoints p1 and p2, the following code sets up three ratios:

length = dist(p1.x, p1.y, p2.x, p2.y); ratioA = (p1.y - p2.y) / length; ratioB = (p2.x - p1.x) / length; ratioC = - 1 * ((p1.y - p2.y) * p1.x + (p2.x - p1.x) * p1.y) / length; Note: these ratios should be recalculated whenever the position of the endpoints change

Once the ratios are set up, the following method can be used to determine the distance from any point to the line:

float distanceFromLine(float x, float y) { return ratioA * x + ratioB * y + ratioC; } Note: this method considers only the infinite-length line, not a specific line segment. Add to this code to check that the point x,y is inside the bounds of the line segment (i.e., it is no further than the length of the line from both p1 and p2).

Part 2B: Scaling and rotation

Interaction Requirements:

 For any selection, the two sliders at the top of the screen will control scaling and rotation
 Both sliders will operate in a relative fashion: that is, you should track the change in the slider rather than its absolute
position. This change is then applied to the rotation or scaling operation.
 The first slider scales the object around its centre point
o Choose a range for the scale slider so that a selected line can be resized from approximately 0.5X to 2.0X
 The second slider rotates the object around its centre point
o The rotation slider’s range should be 4 * PI, such that dragging the slider all the way rotates the object about twice

Software Requirements:

 Add methods to your controller to handle relative changes to the sliders
 Add methods to your Line class to do rotation and scaling
o example code for scale and rotate transforms (in JavaFX) is on the moodle (FXTransformsDemo.zip)
o Remember to translate objects to the origin (based on their centre point) before scaling or rotating
o Remember to update the Line’s ratios after each transformation

When you are finished Part 2:

 Take a snapshot of your project using Android Studio’s “File  Export to Zip file” menu command
o Rename this zipfile “381-A4-Part2.zip”

 You will hand in this zip to show that you have successfully completed Part 2

Part 3: Multiple selection and grouping

Part 3A: Multiple selection

Interaction Requirements:

 If the user long-presses on a line, that line is added to / removed from the selection
o The same “close enough” threshold applies to the long-press location as with single selection
 When there are multiple lines selected, endpoint handles should not be shown; the user can only move an endpoint when
there is a single line selected
 When multiple lines are selected, rotation and scaling operate on all selected lines (each with their own individual rotation /
scaling centre point)

Software Requirements:

 Update your controller to handle the new long-press interactions
 Add a collection to the InteractionModel (e.g., List<Line> selectedLines) to store a set of selected objects
 For any methods in the MVC architecture that use the selection, update the methods to use a selection list

Resources for Part 3A:

 Example code for handling long presses is on the moodle (Android-381LabDemo-Controllers.zip)

Part 3B: Grouping

Interaction Requirements:

 If the user chooses “Group” from the menu when there are multiple lines selected, those lines are grouped
 Groups can also be grouped (and groups of groups, etc.)
 The lines of a group are drawn normally, but the bounding box is also drawn around the group (in cyan)
o All groups show their bounding boxes (including groups within groups)
 If the user touches on any line of a group, the group is selected (and all lines of the group are shown in yellow)
 Grouped objects are translated, scaled, and rotated as a group
o The centre point of the group is used for scaling and rotating
o If the user touches on a group and moves their touch point, the entire group moves
 If a group is selected and the user chooses “Ungroup” from the menu, the group is converted back to individual items
(these remain selected)
o If there is more than one thing selected, or if the selected item is not a group, selecting “Ungroup” from the menu
does nothing.

Software Requirements:

 Add class LineGroup to your project; objects of this class will hold groups of lines
 Add interface Groupable to your project to allow both Lines and LineGroups to coexist in the model and selection (the
Groupable interface will be discussed in lectures)
 Convert the model’s collection of items and the InteractionModel’s selection collection to use type Groupable instead of
type Line

Resources for Part 3B:

 Basics about Java Interfaces are available on the moodle (Java Resources section)

 We will be discussing grouping extensively in class; example code will be posted during that discussion

When you are finished Part 3:

 Take a snapshot of your project using Android Studio’s “File  Export to Zip file” menu command
o Rename this zipfile “381-A4-Part3.zip”
 You will hand in this zip to show that you have successfully completed Part 3

Part 4: Cut/Copy/Paste

Interaction Requirements:

 If there is a selection, choosing “Cut” from the menu puts the selected items on the app’s clipboard and removes them
from the model
o Note: do not use the system clipboard; you must create your own clipboard class
o The selected items can be any Groupable (so, both individual lines and/or groups)
 Choosing “Copy” puts a copy of the selected items on the app’s clipboard
o Only one collection of items can be in the clipboard at a time; if the user copies a second selection, the first one is
discarded from the clipboard
 Choosing “Paste” puts a copy of the item(s) in the clipboard into the model
o The user can paste the items in the clipboard multiple times
o The pasted items become selected when they are pasted; any existing selection is unselected

Software Requirements:

 Menu-selection events are handled by your main activity (method onOptionsItemSelected); this method should then call an
appropriate method in your controller where the real work of cutting and pasting occurs
 Add methods cut, copy, and paste to the model
 Create class SketchClipboard to store items that have been cut or copied
 When copying to the clipboard and when pasting, you will need to make a deep copy of the objects, because you may be
pasting them multiple times, and each paste needs to add different objects to the model

Resources for part 4:

 Details on cut/copy/paste operations: Olsen text, chapter 15
 Tutorial on Java copying: https://dzone.com/articles/java-copy-shallow-vs-deep-in-which-you-will-swim

When you are finished Part 4:

 Take a snapshot of your project using Android Studio’s “File  Export to Zip file” menu command
o Rename this zipfile “381-A4-Part4.zip”
 You will hand in this zip to show that you have successfully completed Part 4

What to hand in

This assignment is to be done individually; each student will hand in an assignment.

 Hand in four zip files as described above, and one readme.txt file that indicates exactly what the marker needs to do to run
your code.
 (Make sure you test all four zip files to make sure they can be opened in Android Studio and run by pressing “run” button)

Where to hand in

Hand in your zip files and readme.txt to the link on the course moodle.

Evaluation

Marks will be given for producing a system that meets the interaction requirements above, that uses an appropriate architecture, that is well organized at the code level, and that compiles and runs without errors. The four parts are equally weighted (all 25%).