Add Gradle and JavaFX tutorials

.gitignore

@@ -0,0 +1 @@
+.idea/

README.md

@@ -1,2 +1,11 @@
-# guides
-Style guides and tutorials for SE student projects
+# Guides and tutorials for SE student projects
+
+## Tutorials
+
+* [Gradle tutorial](tutorials/gradleTutorial.md)
+* JavaFX tutorial:
+  * [Part 1: Introduction](tutorials/javaFxTutorialPart1.md)
+  * [Part 2: Creating a GUI for Duke](tutorials/javaFxTutorialPart2.md)
+  * [Part 3: Interacting with the user](tutorials/javaFxTutorialPart3.md)
+  * [Part 4: Using FXML](tutorials/javaFxTutorialPart4.md)
+

tutorials/assets/DukeSceneGraph.puml

@@ -0,0 +1,24 @@
+@startuml
+hide members
+hide circle
+skinparam shadowing false
+skinparam ClassFontSize 16
+skinparam ClassFontName Arial
+
+class Stage
+class AnchorPane
+class ScrollPane
+class VBox
+class ImageView
+class Label
+
+AnchorPane -up-> Stage
+ScrollPane -up-> AnchorPane
+
+TextField -up-> AnchorPane
+Button -up-> AnchorPane
+
+VBox -up-> ScrollPane
+ImageView -up-> VBox
+Label -up-> VBox
+@enduml

tutorials/assets/JavaFxHierarchy.puml

@@ -0,0 +1,22 @@
+@startuml
+hide members
+hide circle
+skinparam shadowing false
+skinparam ClassFontSize 16
+skinparam ClassFontName Arial
+
+Class Stage
+Class Scene
+Class "Root Node" as RN
+Class Node
+Class "Node" as Node1
+Class "Node" as Node2
+Class "Node" as Node3
+
+Scene -up-> Stage : > must have one
+RN -up-> Scene : > must have one
+Node -up-> RN : > can have zero or more
+Node1 -up-> Node
+Node2 -up-> Node
+Node3 -up-> Node
+@enduml

tutorials/checkstyleTutorial.md

@@ -0,0 +1 @@
+TBD

tutorials/gradleTutorial.md

@@ -0,0 +1,130 @@
+# Gradle Tutorial
+
+Gradle is a _build automation tool_ used to automate build processes. There are many ways of integrating Gradle into a project. This tutorial uses the _Gradle wrapper_ approach.
+
+* [Basics](#basics)
+* [Adding Gradle to the project](#adding-gradle-to-the-project)
+* [Running Gradle tasks](#running-gradle-tasks)
+* [Adding plugins](#adding-plugins)
+* [Using Gradle to do some common project activities](#using-gradle-to-do-some-common-project-activities)
+  * [Running CheckStyle](#running-checkstyle)
+  * [Running tests](#running-tests)
+  * [Creating a JAR file](#creating-a-jar-file)
+* [Managing dependencies](#managing-dependencies)
+* [Further reading](#further-reading)
+
+## Basics
+
+You use a _build file_ (named `build.gradle`) to describes the project to Gradle. A build file mainly consists of _plugins_, _tasks_ and _properties_. 
+
+* **Plugins** extend the functionality of Gradle. For example, the `java` plugin adds support for `Java` projects.
+
+* **Tasks** are reusable blocks of logic. For example, the task `clean` simply deletes the project build directory. 
+Tasks can be composed of, or dependent on, other tasks. 
+
+* **Properties** change the behavior of tasks. For instance, `mainClassName` of the `application` plugin is a compulsory property which tells Gradle which class is the entry point to your application. As Gradle favors [_convention over configuration_](https://en.wikipedia.org/wiki/Convention_over_configuration), there is not much to you need to configure if you follow the recommended directory structure.
+
+
+## Adding Gradle to the project
+
+For simplicity, let us assume that Gradle Wrapper has been added to the project already (if it has been added to the project, you will see a `gradle\wrapper\gradle-wrapper.jar` in your project). If you need to add it yourself, you can learn how to do that from [here](https://docs.gradle.org/current/userguide/gradle_wrapper.html).
+
+
+## Using Gradle in Intellij IDEA
+
+When you import a Gradle project into IntelliJ IDEA, you should select the `build.gradle` instead of the project root directory. After importing a Gradle project into Intellij IDEA, you will see the `Gradle Toolbar` in the IDEA interface.<br>
+![Gradle icon](assets/GradleIcon.png)
+
+If the Gradle tasks don't appear in the Gradle window, click the 'refresh' button in the tooolbar to reimport the Gradle project.
+
+Intellij uses Gradle to run your application by default. If you would like to run the project in the normal way, go to `File` > `Settings` and change the following settings:<br>
+![change Intellij settings to not use Gradle](assets/intellijRunUsingGradle.png)
+
+
+## Running Gradle Tasks
+
+To run a task, locate the task in the Gradle toolbar, right-click on a task, and choose `run`.
+
+Alternatively, you can type the command in the terminal.
+
+* On Windows: `gradlew <task1> <task2> …`​ e.g. `gradlew clean test`
+* On Mac/Linux: `./gradlew <task1> <task2> …`​ e.g. `./gradlew clean test`
+
+
+## Adding plugins
+
+Gradle plugins are reusable units of build logic. Most common build tasks are bundled into core plugins provided by Gradle. Java, CheckStyle, and Shadow are three of plugins commonly used in Java projects.
+The relevant lines of the `build.gradle` are given below:
+
+```groovy
+plugins {
+    id 'java'
+    id 'application'
+    id 'checkstyle'
+    id 'com.github.johnrengelman.shadow' version '5.1.0'
+}
+```
+
+## Using Gradle to do some common project activities
+
+### Running CheckStyle
+
+CheckStyle is a tool for checking if the code complies with certain style rules.
+
+Checkstyle expects configuration files for checkstyle (e.g., files that specify which style rules to follow) to be in `./config/checkstyle/` by convention.
+
+The plugin adds a few _tasks_ to your project.
+* `checkstyleMain`: checks if the main code complies with the style rules
+* `checkstyleTest`: checks if the test code complies with the style rules
+
+For example, you can run `gradlew checkstyleMain checkstyleTest` to verify that all your code complies with the style rules.
+
+**Resources**:
+* [Gradle documentation for the CheckStyle plugin](https://docs.gradle.org/current/userguide/checkstyle_plugin.html)
+
+
+### Running tests
+
+Run the `test` task to run the tests in the project.
+
+
+**Resources**:
+* [Gradle documentation for JUnit](https://docs.gradle.org/current/userguide/java_testing.html#using_junit5)
+
+
+### Creating a JAR file
+
+Shadow is a plugin that packages an application into an executable jar file. 
+
+The plugin can be configured by setting some properties. By default, it produces a jar file with the name in the format of `{archiveBaseName}-{archiveVersion}.jar` (the two properties can be set in the `build.gradle` file).
+
+You can generate an executable jar by running the command `gradlew shadowJar` which publishes an executable jar to `./build/libs/`.
+
+**Resources**:
+* [Gradle documentation for the Shadow plugin](https://plugins.gradle.org/plugin/com.github.johnrengelman.shadow)
+* [More about the Shadow plugin](https://imperceptiblethoughts.com/shadow/introduction/)
+
+
+## Managing dependencies
+
+Gradle can automate the management of dependencies to third-party libraries. You just need to add the dependency into the `build.gradle` file and Gradle will do the rest. For example, here is how the JUnit library has been added to the dependencies in the `build.gradle`:
+```groovy
+dependencies {
+    testImplementation group: 'org.junit.jupiter', name: 'junit-jupiter-api', version: '5.5.0'
+}
+```
+
+For example, to add the Natty (a third-party library used for parsing natural lanaguage dates e.g., `today`), you simply have to add the following line to the `dependencies` section of the `build.gradle` file.
+```groovy
+compile group: 'com.joestelmach', name: 'natty', version: '0.6'
+```
+
+Tip: Most third-party libararies specify how to add it as a Gradle dependency ([example](https://mvnrepository.com/artifact/com.joestelmach/natty/0.6)).
+
+## Further reading
+
+* [Official Gradle Documentation](https://docs.gradle.org/current/userguide/userguide.html)
+
+----------------------------------------------------------------------------------------
+**Authors:**
+* Initial Version: Jeffry Lum

tutorials/javaFxTutorialPart1.md

@@ -0,0 +1,117 @@
+# JavaFX Tutorial Part 1 – Introduction
+
+## Lifecycle of a JavaFX  application
+
+Imagine yourself as a director of a play. First you provision the props that you will feature in your play. These can be hand props for your actors to interact with or even set dressings just to liven up the background. You then decide where to layout the props for every scene. With a proper script in hand, you can finally approach a theatre and request for a stage. There on, it’s just a matter of pulling the curtains on your masterpiece.
+
+![Hierarchy of Objects in JavaFX](assets/JavaFxHierarchy.png)
+
+A JavaFX application is like a play you are directing. Instead of creating props, you create `Nodes` (`Nodes` are the fundamental building blocks of a JavaFX application), and place them onto a `Scene` (a scene is a graph of `Node`s). Then, you set your `Scene` on a `Stage` provided by JavaFX. When you call `Stage#show()` method, JavaFX renders a window with your `Stage` on it.
+
+## Setting up Java FX
+
+### If you are not using Gradle
+
+1. Download the [JavaFX 11 SDK](https://gluonhq.com/products/javafx/) and unzip it.
+
+1. Import the `libs` folder from the SDK into your project (note: `JAVAFX_HOME` is the directory in which you have unzipped the JavaFX SDK). 
+
+   `File` > `Project Structure` > `Libraries` > `+` > `Java` > `{JAVAFX_HOME}/lib`
+
+1. From `Run` > `Edit Configurations`, add the following line into your `VM options` for each of the `main` classes.
+
+   `--module-path {JAVAFX_HOME}/lib --add-modules javafx.controls,javafx.fxml`<br>
+   e.g., `--module-path C:/javafx-sdk-11.0.2/lib --add-modules javafx.controls,javafx.fxml`
+
+### If you are using Gradle
+
+Update your `build.gradle` to include the following lines:
+```groovy
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    String javaFxVersion = '11'
+
+    implementation group: 'org.openjfx', name: 'javafx-base', version: javaFxVersion, classifier: 'win'
+    implementation group: 'org.openjfx', name: 'javafx-base', version: javaFxVersion, classifier: 'mac'
+    implementation group: 'org.openjfx', name: 'javafx-base', version: javaFxVersion, classifier: 'linux'
+    implementation group: 'org.openjfx', name: 'javafx-controls', version: javaFxVersion, classifier: 'win'
+    implementation group: 'org.openjfx', name: 'javafx-controls', version: javaFxVersion, classifier: 'mac'
+    implementation group: 'org.openjfx', name: 'javafx-controls', version: javaFxVersion, classifier: 'linux'
+    implementation group: 'org.openjfx', name: 'javafx-fxml', version: javaFxVersion, classifier: 'win'
+    implementation group: 'org.openjfx', name: 'javafx-fxml', version: javaFxVersion, classifier: 'mac'
+    implementation group: 'org.openjfx', name: 'javafx-fxml', version: javaFxVersion, classifier: 'linux'
+    implementation group: 'org.openjfx', name: 'javafx-graphics', version: javaFxVersion, classifier: 'win'
+    implementation group: 'org.openjfx', name: 'javafx-graphics', version: javaFxVersion, classifier: 'mac'
+    implementation group: 'org.openjfx', name: 'javafx-graphics', version: javaFxVersion, classifier: 'linux'
+}
+```
+
+## Writing your first program
+
+As customary, let’s start off with a simple “Hello World” program. Let's say you have a class named `Duke` that you want make a GUI. First, modify the `Duke` class to extend `javafx.application.Application`. This requires you to override the `Application#start()` method and provide a concrete implementation. Notice that the method signature for `Application#start()` has a parameter `Stage`. This is the _primary stage_ that JavaFX provides.
+
+```java
+import javafx.application.Application;
+import javafx.scene.Scene;
+import javafx.scene.control.Label;
+import javafx.stage.Stage;
+
+public class Duke extends Application {
+
+    // ...
+
+    @Override
+    public void start(Stage stage) {
+        Label helloWorld = new Label("Hello World!"); // Creating a new Label control
+        Scene scene = new Scene(helloWorld); // Setting the scene to be our Label
+
+        stage.setScene(scene); // Setting the stage to show our screen
+        stage.show(); // Render the stage.
+    }
+}
+```
+
+Note how we have created a `Label` to contain the text that we want to show. We then create the `Scene` and set its content. Finally, we set the stage and show it. 
+
+Next, we create another Java class, `Launcher`, as an entry point to our application.
+The `Launcher` class is reproduced below in its entirety.
+
+```java
+import javafx.application.Application;
+
+/**
+ * A launcher class to workaround classpath issues.
+ */
+public class Launcher {
+    public static void main(String[] args) {
+        Application.launch(Duke.class, args);
+    }
+}
+```
+
+Run `Launcher` and you should see something like this:
+
+![Hello World](assets/HelloWorld.png) 
+
+Congratulations! You have created your first GUI application!
+
+## Exercises
+
+1. We mentioned that `Node`s are the fundamental building blocks of JavaFX and used a `Label` as our root node in the HelloWorld application.
+   1. What are some of the other types of `Node`s?
+   1. How does JavaFX group them?
+
+1. `Node`s can be interacted with like Plain Old Java Objects (POJO).
+   1. What properties of a `Label` can you change programmatically?
+   1. Try changing the `Label` to have a font of Arial at size 50.
+
+1. You’ve learnt that a `Stage` can be thought of as a window. 
+   1. Can you have more than one `Stage` an application?
+   1. Try creating another stage and showing it! What happens?
+
+--------------------------------------------------------------------------------
+**Authors:**
+* Initial Version: Jeffry Lum