Cartoon - HackMD

# Cartoon :::danger Early Handin: Thursday, October 17, 2024 Regular Handin: Saturday, October 19, 2024 Late Handin: Monday, October 21, 2024 ::: Watch the demo [here](https://www.youtube.com/watch?v=_L4dczto6HM)! Check out the mini assignment [here](https://hackmd.io/@Fall2024-CS15/SJzfSS0i0)! # Assignment Roadmap :::info [Silly Premise](#Silly-Premise) [Collaboration Policy Reminder](#Collaboration-Policy-Reminder) [New Concepts Covered](#New-Concepts-Covered) [Helpful Resources](#Helpful-Resources) [Installing Stencil Code](#Installing-Stencil-Code) [Grading](#Grading) ### [FUNCTIONALITY ](#Functionality) [Recommended: Personal Connection](#Recommended:-Personal-Connection) [Coding Incrementally](#Coding-Incrementally) [Suggested Order for Incremental Coding](#Suggested-Order-for-Incremental-Coding) [TA Checkpoint](#TA-Checkpoint) [Minimum Functionality Requirements](#Minimum-Functionality-Requirements) [Full Functionality Requirements](#Full-Functionality-Requirements) [Bells and Whistles](#Bells-and-Whistles) ### [IMPLEMENTATION ](#Implementation) [App Class](#App-Class) [JavaFX](#JavaFX) [Keyboard Interaction](#Keyboard-Interaction) [More JavaFX Resources](#More-JavaFX-Resources) ### [DESIGN ](#Design) ### [STYLE ](#Style) ### [HANDING IN ](#Handing-In) [README](#README) [Handin](#Handin) ::: ## Silly Premise The Ember Island Players are putting on a new play based on the adventures of Team Avatar! They took Sokka's critique that "the effects were half decent" to heart, and now they want to make the best production ever. They're looking for world class artists, actors, and animators from all over the four nations! Try your hand and audition by making an awesome Cartoon! Reference: Avatar the Last Airbender, Nickelodeon ![MV5BYjMyYTdkOWQtNjYxZC00ODFiLTk0NTgtNzk2MGM2NzE3YjgyXkEyXkFqcGdeQXVyMjgyOTI4Mg@@._V1_](https://hackmd.io/_uploads/S1fLt-zn0.jpg) ## Collaboration Policy Reminder If you ever have questions about [the collaboration policy](https://docs.google.com/document/d/10rbbd0Y6s1JUzPe8VmoWcL_Mz26XczX-i7p2LUFa9vc/edit?usp=sharing), refer to the collaboration policy or ask a TA! <img style="display: block; margin: auto; padding-top: 15px;" src=https://hackmd.io/_uploads/BkSOpo1nC.png width=600px> :::danger **Note:** The usage of any artificial intelligence technologies, except those explicitly endorsed by CS15, is *strictly prohibited*. Because of TAs reading your code and a software package we use called MOSS (Measure of Software Similarity), illegal collaboration is easily detected in CS15. ::: ## New Concepts Covered * GUIs (Graphical User Interfaces) * Graphical Containment * Layout Management * Complex association and sharing references * Events and event handling * JavaFX * Lambda expressions ## Helpful Resources * This handout! * [JavaFX & Design Code-along Recording](https://www.youtube.com/watch?v=cMVLdmCxMr0) * The [demo](https://www.youtube.com/watch?v=_L4dczto6HM) * [JavaFX Javadocs](https://docs.oracle.com/javase/8/javafx/api/toc.htm) * [Style Guide](https://docs.google.com/document/d/1olSJxbrhuIystA_kVbmKu4V8JfN7HE-eDzM5blkoeFw/edit?usp=sharing), [GitHub Guide](https://docs.google.com/document/d/1tSxfUIn-Ro6Pr1X4y21BbYKdsiK-nlWW3pGDfyh7SQ8/edit?usp=sharing), and [README Guide](https://docs.google.com/document/d/1QJPit-_8ZC3r4l_f5F3ydMK34-NchBYgwtm0c21iwsU/edit?usp=sharing) * [CS15 JavaFX Guide](https://docs.google.com/document/d/1cOq649OLNp0-UHxz5W5KAOH-KyM2VXvq_TKmuGHv0Rg/edit?usp=sharing) * [Getting started with JavaFX](https://docs.oracle.com/javafx/2/get_started/jfxpub-get_started.htm) * [Using Images in JavaFX](https://docs.google.com/document/d/1GBzrVsdlc1r5wJXqG88i_EL5mQSV6gx-b_mJDJ8vYR4/edit#heading=h.vzeutseexo66) * [Graphics I Lecture](https://cs.brown.edu/courses/cs015/lecture/pdf/CS15.Lecture_9_Graphics_Part_I.10.3.24.pdf), [Graphics II Lecture](https://cs.brown.edu/courses/cs015/lecture/pdf/CS15.Lecture_10_Graphics_Part_II.10.8.24.pdf), [Graphics III Lecture](https://cs.brown.edu/courses/cs015/lecture/pdf/CS15.Lecture_11_Graphics_Part_III.10.10.24.pdf) * [Draw.io](https://app.diagrams.net/) * Cartoon [Help Slides](https://docs.google.com/presentation/d/1RsEskD5K6qo7q3QyR9XMaUgHrRzqLIg2x-L8mtTAf9k/edit#slide=id.p4) ## Installing Stencil Code Click **[here](https://classroom.github.com/a/Ao9YTCCL)** to get the stencil from GitHub - refer to the [CS15 GitHub Guide](https://docs.google.com/document/d/1tSxfUIn-Ro6Pr1X4y21BbYKdsiK-nlWW3pGDfyh7SQ8/edit) for help with GitHub and GitHub Classroom. Once you’ve cloned your personal repository from GitHub, you’ll need to rename the folder from **`cartoon-<yourGitHubLogin>`** to just **`cartoon`**. You will have issues running your code until you make the change. ## Grading The grade for this assignment will be determined by [functionality](#Functionality) (50%), [design](#Design) (35%), and [style](#Style) (15%). See each of those sections for more details of this grading breakdown. An ‘A’ project would meet mostly all [full functionality requirements](#Full-Functionality-Requirements) with good design and style. --- # Functionality Here's your chance to be creative with JavaFX. While we require that you implement some standard base functionality, we also want you to be creative with this. **This means you may not simply make the alien from the lecture slides.** The assignment specification, at a high level, is to create a graphical user interface (GUI) that accomplishes a few small tasks and uses a composite shape (a class that is "composed of" multiple **`javafx.scene.shape.Shape`** s). After you have the base specs working, use your imagination, artistic ability (let's see it, you VISA concentrators!), and programming skills to make something that wows your friends. As with all projects, you are expected to follow CS15 design conventions. This includes the use of a **`PaneOrganizer`** class (see “Programming Tips” section and Help Slides posted online), a top-level logic **`Cartoon`** class, constants, and helper methods as needed. ## Minimum Functionality Requirements <img style="float: right;" width="150" src="https://hackmd.io/_uploads/H1RfT3J3R.png"></img> MF Policy Summary: *To pass CS15, you will have to meet minimum functionality requirements for all projects. If you don’t meet them the first time around, you may hand the project in again until you succeed, but you will keep your original grade. MF requirements are not the same as the requirements for full credit on the project. You should attempt the full requirements on every project to keep pace with the course material. An ‘A’ project would meet all of the requirements on the handout and have good design and code style.* To provide some direction, we require the following elements. Before you even start thinking about extra parts of this assignment, make sure you have the following: * A composite shape that moves based on a **`javafx.animation.Timeline`** used to animate your Cartoon. * Composite shape is composed of at least <ins>5 shapes (they can be the same shape)</ins> * ***For full credit***: use at least <ins>2 distinct types</ins> of shapes from the **`javafx.scene.shape`** package * Some of the classes you could use are **`Circle`**, **`Rectangle`**, and **`Polygon`**. * The use of the **`javafx.scene.layout`** package so that your components line up nicely within your GUI. * Some useful layout containers are **`BorderPane`**, **`VBox`**, **`HBox`**, **`FlowPane`**, and **`GridPane`** classes. * A **`javafx.scene.control.Label`** that changes * For **minimum functionality**: the text value of your **`Label`** must change at any point during the cartoon (based on key input, the movement of your composite shape, the location of your composite shape, etc). * For **full credit**: the text content of your **`Label`** should change (be creative with how the label can achieve this — you don’t have to just increment a counter with increasing time) as the timeline is updated. The **`Label`** should change based on the same **`Timeline`** that animates your composite shape. If your **`Label`** **only changes with key input**, your grade will receive a deduction. * An **`EventHandler`** that can visually change an element of your cartoon (think moving shapes, changing colors, etc.) based on keyboard input (**`KeyEvents`**) without quitting. * i.e., your program must be set up so that pressing a button on the keyboard causes a visible change in the cartoon. * A **`javafx.scene.control.Button`** that *quits your program properly* * This button will need an **`EventHandler`** that calls **`System.exit(0)`**, which exits the program ## Full Functionality Requirements Beyond the minimum functionality requirements, the rest of the functionality grade will depend on the following criteria: * Your composite shape must use at least two different types of **`javafx.scene.shape.Shape`**. (e.g. **`Circle`**, **`Rectangle`**, **`Polygon`**) * The text **`Label`** described in MF must update with the **`Timeline`**, not just with key input. * Your cartoon implements at least one design feature that improves its accessibility (based on what you learned in the SRC lecture on accessible design). Explain your choice in your [README](#README). * No minor bugs ## Recommended: Personal Connection This is the first project that’s completely your own - make it personal! We’re not giving you any support code so when you’re finished you’ll have a project you made completely from scratch. **We’d love to see cartoons that mean something to you**. You can make a cartoon of your pet, your childhood home, your favorite vacation spot, your favorite childhood toy, your favorite food, your favorite childhood cartoon character, or anything else you love. Make sure to tell us about the personal connection in your README and how your cartoon features it! When the TAs choose to showcase their favorite cartoons, we love cartoons with personal significance! *hint hint* ## Coding Incrementally After you’ve watched the [demo](https://youtu.be/_L4dczto6HM), *thoroughly read this handout* to make sure you understand the project design. Once you’re ready, start coding! It is important to code **incrementally**, meaning you completely accomplish one logical task before moving on to the next one. ## Suggested Order for Incremental Coding **It is a very good idea to code this assignment *incrementally***, making sure it compiles and does what you expect at each step. Coding incrementally will save you a significant amount of time on this project. Feel free to work in any order that works for you, but the Help Slides break down one way to approach the project in chunks so that you can get small parts working with each step. **Step 0.** Complete the [Mini Assignment](https://hackmd.io/@Fall2024-CS15/SJzfSS0i0) (make a plan for your cartoon!). **Step 1.** Get your stage to show up on the screen! The [help slides](https://docs.google.com/presentation/d/1RsEskD5K6qo7q3QyR9XMaUgHrRzqLIg2x-L8mtTAf9k/edit?usp=sharing) break down how you can do this in more detail. **Step 2.** Create an instance of your **`Cartoon`** class, making sure it shows up. Once you have that, add any shapes, labels, and other elements to help your Cartoon come together. **Step 3.** Add an **`EventHandler`** that can allow you to interact with your cartoon! **Step 4.** Add a **`Timeline`** to animate your cartoon **Step 5.** Reread the requirements listed above to **triple-check** that you meet all the requirements. We often receive submissions that do not meet Minimum Functionality for silly reasons because the requirements weren’t read carefully. Don’t forget to make sure that you have all the required components in your cartoon! :::success ### **TA Checkpoint** This project will have a checkpoint early on to ensure you’re on track and answer any questions you might have! You'll be getting your mini assignment checked off during lab 5. **The checkpoint is early on in the project. If your lab is later in the week, you should be significantly ahead of the checkpoint by that time. The checkpoint is just a general guide.** For this checkpoint, all you need to do is: 1. Complete steps 1 and 2 of the incremental coding above (fill in your **`App`** class to make your project window appear!) 2. Create the 4 core classes you’ll need for your cartoon (see class & inheritance/interface diagram under [design](#Design)), even if they’re mostly empty for now 3. Have at least one **`Pane`** appear, with at least one **`Shape`** added to that pane in your composite shape class 4. Something in your program must respond to key input; it doesn’t need to be your final plan for handling key input! ::: ## Bells and Whistles If you want to add extra credit to your assignment, check out the snazzy demos from lecture for inspiration. Additionally, here are some possible ideas, but you may certainly come up with your own: * Use polymorphism in a meaningful way! * Include other JavaFX elements, like **`javafx.scene.control.Slider`**, **`javafx.scene.control.ColorPicker`**, **`javafx.scene.control.Spinner`**, or some other element to interact with your Cartoon in even more ways. The possibilities are endless! * Find a way to have mouse *AND* keyboard interactions! * Add images! Read more [here](https://docs.oracle.com/javase/8/javafx/api/javafx/scene/image/ImageView.html). * Note: if you are adding an image, use “**`./cartoon/<image_name>`**” so that it runs properly when we are grading. If you do not submit the image with your code when handing in your project, you will not get credit for the use of images. * Make your Cartoon out of 3D shapes. You can read about how to use them [here](https://docs.oracle.com/javase/8/javafx/graphics-tutorial/shape3d.htm). * Make fancy transitions! There are many transition animation effects provided in JavaFX such as **`FadeTransition`**, **`ParallelTransition`**, **`PathTransition`**, **`RotateTransition`**, and so on. Read more [here](https://docs.oracle.com/javase/8/javafx/api/javafx/animation/Transition.html). * Add some cool effects to your shapes/text! See the [Javadocs](https://docs.oracle.com/javase/8/javafx/api/javafx/scene/effect/package-summary.html) for possible effects. * Make your shape move at different speeds, by adding in a [javafx.scene.effect](https://docs.oracle.com/javase/8/javafx/api/javafx/scene/effect/package-summary.html) acceleration variable! The movement must be based on a **`Timeline`**, but the changes in speed can happen based on the **`Timeline`** or based on another factor (e.g. keyboard input). Manually setting (hardcoding) speeds will not count. Remember that you should make sure that you have a fully functional program before working on extra credit. Remember, from the [Course Missive](https://docs.google.com/document/d/1_zT7i5ApBusdW0GKzz5U939mZBQD02p5wG5e8V49cbg/edit?usp=sharing): >“Extra credit is only to be done after the original assignment has been fully completed - if you have not met the requirements, you will not receive extra credit. Extra credit may not redefine the original assignment.” --- # Implementation ## App Class The stencil code we give you consists of an **`App`** that takes care of the mainline. It’s your job to override and fill in the **`public void start(Stage stage)`** method. Here you can instantiate your top-level **`PaneOrganizer`**. Also, make sure to set a new scene and pass in your root pane. ## JavaFX Cartoon is your first project without support code written by the TAs—congratulations! From here on out, you’ll be using lots of JavaFX code. Just like support code, all of this is written for you, so you don’t need to worry about how any of this is implemented; all you need to do is call methods as they are defined. We **highly** recommend that you review the lecture slides of [Graphics I](https://cs.brown.edu/courses/cs015/lecture/pdf/CS15.Lecture_9_Graphics_Part_I.10.3.24.pdf), [Graphics II](https://cs.brown.edu/courses/cs015/lecture/pdf/CS15.Lecture_10_Graphics_Part_II.10.8.24.pdf), and [Graphics III](https://cs.brown.edu/courses/cs015/lecture/pdf/CS15.Lecture_11_Graphics_Part_III.10.10.24.pdf), as well as read through the [CS15 JavaFX Guide](https://docs.google.com/document/d/1cOq649OLNp0-UHxz5W5KAOH-KyM2VXvq_TKmuGHv0Rg/edit?usp=sharing) before you start. Refer to these lectures and additional resources as you work on your cartoon. ***Make sure you understand the lecture slides and the JavaFX Shapes Documentation before you begin working on the project!*** Feel free to refer to CS15 JavaFX Guide if you need more examples, or need some guidance in adding bells & whistles to your cartoon. The JavaFX Guide provides all of the explanations of the classes, methods, and common pitfalls that you need to know for Cartoon. ***Reading these documents will save you a significant amount of time when coding and debugging.*** Once you have completed it, the JavaFX lab will also cover many of the concepts and code that can jumpstart your work on this project, so we would recommend completing that lab before you start coding for Cartoon. ### Keyboard Interaction You may be wondering how you will make your cartoon respond to user input. The answer is keyboard interaction! There are a few ways to do keyboard interaction in Java, though we suggest the method below. (Feel free to explore [Javadocs](https://docs.oracle.com/javase/8/javafx/api/javafx/event/EventHandler.html) for other ways to go about it, as long as they work well and are readable). The method we recommend makes use of the interface **`javafx.event.EventHandler`**. You need to use a lambda expression to implement this Event Handler and tell it what code it should execute. To get information on which key is being pressed, you should create a helper method that takes in a **`KeyEvent`** and is called using a lambda expression whenever your program registers a key press. An example of this structure is below. Then, you need to call the method **`getCode()`** on the **`KeyEvent`** which will report which keyboard key (**`KeyCode`**) has been pressed. Read more about **`KeyEvents`** [here](https://docs.google.com/document/d/1cOq649OLNp0-UHxz5W5KAOH-KyM2VXvq_TKmuGHv0Rg/edit?usp=sharing) (jump to the section on “KeyBoard Input”). For a complete list of the types of **`KeyCodes`**, you can check the [Javadocs](https://docs.oracle.com/javase/8/javafx/api/javafx/scene/input/KeyCode.html). Once you know what keyboard key was pressed, you can *make a decision* (hint, hint... [“Math and Making Decisions” lecture slides](https://cs.brown.edu/courses/cs015/lecture/pdf/CS15.Lecture_8_Math_and_Making_Decisions.10.1.24.pdf)) on what you want to do when a specific key is pressed. Let’s add keyboard functionality to a pane in our Cartoon class to move something. We’ll use a lambda expression in the constructor of the Cartoon class and create a helper method that takes in the **`KeyEvent`** generated when a key is pressed. ``` public Cartoon(Pane cartoonPane) { //constructor //other code elided cartoonPane.setOnKeyPressed((KeyEvent e) -> this.onKeyPressed(e)); } private void onKeyPressed(KeyEvent event) { switch(event.getCode()) { case UP: //code to make something move up break; case DOWN: //code to make something move down break; default: //code to do something else (if you want) break; } e.consume(); //don’t forget to call this! } ``` *A few important notes to keep in mind regarding keyboard interaction:* JavaFX has some built-in functionality for certain **`KeyEvents`**. For example, the down arrow key moves the input focus to another node in the scene graph. Depending on your Cartoon implementation, this may mean that pressing down would move the focus out of the **`Pane`** that holds your cartoon and into another, which can cause all sorts of issues! There are two steps that you should take to fix this: 1. Call the **`consume()`** method on the **`KeyEvent`** * One way to make sure the program only executes what you indicate in the **`EventHandler`** is to “consume” the event, which you can think of as throwing away the event after it has done everything you need it to do. To do this, call the **`consume()`** method on the **`KeyEvent`** at the end of the method you use it in. You can read more about this [here](http://docs.oracle.com/javafx/2/events/processing.htm#CEGJAAFD) (in the section under “Consuming of an Event” at the bottom of the page.) 2. Call the **`setFocusTraversable(...)`** method on the relevant **`Panes`** * We can also explicitly manage where focus is set. To do this, you’ll need to make sure to call **`setFocusTraversable(true)`** on the **`Pane`** that listens to your **`KeyEvents`**. To make sure no other node (in this case, the quit button) grabs focus inadvertently, you can call **`setFocusTraversable(false)`** on each one. You can read about this method [here](http://docs.oracle.com/javafx/2/api/javafx/scene/Node.html#setFocusTraversable(boolean)). ## More JavaFX Resources You can check out the [Javadocs](https://docs.oracle.com/javase/8/javafx/api/toc.htm) for loads of JavaFX Documentation -- these are great resources for finding the methods and properties of JavaFX elements! However, the [CS15 JavaFX Guide](https://docs.google.com/document/d/1cOq649OLNp0-UHxz5W5KAOH-KyM2VXvq_TKmuGHv0Rg/edit?usp=sharing) provides a lot of implementation & ideal design details that the JavaDocs don’t cover in as much depth, so use the JavaDocs to supplement the CS15 JavaFX guide, rather than replace it. For even more resources, you can check out this [tutorial](http://docs.oracle.com/javafx/2/get_started/jfxpub-get_started.htm) that Oracle provides on getting used to JavaFX. “Hello World, JavaFX Style” and “Form Design in JavaFX” will help you learn the basic layout design. Also, you can take a look at “Animated Shapes and Visual Effects” to learn how **`Timeline`** is used, but you do not need to get as fancy in your Cartoon project. --- # Design ## Class Design & Delegation <img style="float: right; margin-left: 30px;" width="200" src="https://hackmd.io/_uploads/HkMayqFkkx.png"></img> In previous projects, we’ve had one top-level class. Moving forwards, we will have two: a top-level graphic class (**`PaneOrganizer`**) and a top-level logic class (e.g., **`PongGame`** or **`Cartoon`**). As the top-level graphic class, **`PaneOrganizer`** should really only be responsible for high-level graphical elements that affect your entire application (not all graphical elements though!). Imagine an application that had several different games happening at once—it would be a lot of work for the **`PaneOrganizer`** to keep track of every single shape in every single game. For the Cartoon project, your **`PaneOrganizer`** should not be responsible for controlling your shapes and animation. Instead, **`PaneOrganizer`** can **delegate** most of the responsibility for animation and user input to another class—your **`Cartoon`** class, or the top-level logic class! You should also be sure to use a composite shape class (like Alien from the [Graphics III lecture](https://cs.brown.edu/courses/cs015/lecture/pdf/CS15.Lecture_11_Graphics_Part_III.10.10.24.pdf)!) to handle the specific movement and manipulation of the JavaFX shapes that create your composite shape. --- # Style Refer to the [CS15 Style Guide](https://docs.google.com/document/d/1olSJxbrhuIystA_kVbmKu4V8JfN7HE-eDzM5blkoeFw/edit) for the specific style guidelines along which your code will be graded for the “style” portion. # Handing In ## README In CS15, you’re required to hand in a README file (must be named README) that documents any notable design choices or known bugs in your program. Since designs for Cartoon are unique, it is going to be extra important that you write a clear README that explains how to interact with your Cartoon, and states the design choices that you made. Your visual changes and inputs should all be explained in the README. Remember, the TAs look over your README before grading Cartoon, so make them happy and explain all significant design choices. Label a section in your README titled ‘**SRC**’. Include a description of at least one way you’ve made an effort to improve the accessibility of your cartoon. For ideas on ways to do this, revisit the [SRC mini-lecture](https://cs.brown.edu/courses/cs015/lecture/pdf/CS15.Lecture_11_Graphics_Part_III.10.10.24.pdf). You are expected to create your own README file. Please refer to the [README guide](https://docs.google.com/document/d/1QJPit-_8ZC3r4l_f5F3ydMK34-NchBYgwtm0c21iwsU/edit) for information on how to create a README, what information your README should contain, and how you must format it. At the bottom of your README, add the approximate hours you spent on this project. This will be used only to average how long the projects are taking students this semester, and it is completely anonymous. ## Handin To hand in your assignment, follow these steps: 1. In a terminal, move into the **`cartoon`** folder 3. Type the command **`rm *.class`** (Mac) or **`del *.class`** (Windows) * This will remove the **`.class`** files that are created when compiling so that your submission only includes **`.java`** code files. 3. [Add, commit, and push your code to GitHub](https://docs.google.com/document/d/1tSxfUIn-Ro6Pr1X4y21BbYKdsiK-nlWW3pGDfyh7SQ8/edit?usp=sharing) 4. Add your class and interface/inheritance (if you used any) diagrams to your GitHub repository * Drag and drop or upload your class and inheritance/interface diagrams to your cartoon folder 5. In the submission for Cartoon on Gradescope, click on GitHub 6. Select your ++Cartoon++ repository and the ++main++ branch 7. Upload! Make sure to **quintuple-check** that the correct version of your code has been pushed to GitHub and submitted to Gradescope before the deadline! If the deadline is approaching and there is an error pushing your code to GitHub, you will have to use a late day to solve the error or stick with the version of your code that is already on Gradescope. You can submit as many times as you want before the deadline, and only your most recent handin will be graded. If you handin before the deadline and again after the deadline, the submission will be counted as late. **Do not include any identifying information on your handin, including file names (name, login, Banner ID) as we grade anonymously. Including identifying information will result in a deduction from your assignment.** Good luck and remember: **Start Early... Start Today... Start Yesterday!** - William Shakespeare <img src="https://hackmd.io/_uploads/rkqbIPX3R.jpg" alt="Avatar picture" width="500" style="display: block; margin: auto">