Merge pull request #551 from RichDom2185/week13/update-dg

Update DG with UI Implementation
AY2223S1-CS2103T-W16-2 · Nov 7, 2022 · ffc5c7b · ffc5c7b
2 parents c1595af + 6acd958
commit ffc5c7b
Show file tree

Hide file tree

Showing 12 changed files with 118 additions and 15 deletions.
diff --git a/docs/_dg/AboutDG.md b/docs/_dg/AboutDG.md
@@ -1,7 +1,8 @@
 <!-- markdownlint-disable-file first-line-h1 -->
 <!-- markdownlint-disable-next-line proper-names -->
 {{ site.data.foodrem.about.summary_dg }}
-This Developer Guide provides in-depth documentation on how FoodRem is designed and implemented. It covers the architecture of FoodRem, detailed specifications on smaller pieces of the design, and an outline of all parts of the software and how they will work. 
+
+This Developer Guide provides in-depth documentation on how FoodRem is designed and implemented. It covers the architecture of FoodRem, detailed specifications on smaller pieces of the design, and an outline of all parts of the software and how they will work.
 
 You can use this guide to maintain, upgrade, and evolve FoodRem.
 

diff --git a/docs/_dg/Effort.md b/docs/_dg/Effort.md
@@ -9,4 +9,4 @@ One challenge we ran into during the project was implementing a batch feature fo
 
 ### Revamping of UI
 
-We wanted a simple yet appealing [[ graphical-user-interface:graphical user interface ]] for our application's users. As such, we decided to change the original UI of AB3 into our own new FoodRem UI. As our team was not familiar with JavaFX initially, it took us considerable time and effort to produce an eventual satisfactory and working UI that we were proud to adopt and incorporate into our application. 
+We wanted a simple yet appealing [[ graphical-user-interface:graphical user interface ]] for our application's users. As such, we decided to change the original UI of AB3 into our own new FoodRem UI. As our team was not familiar with JavaFX initially, it took us considerable time and effort to produce an eventual satisfactory and working UI that we were proud to adopt and incorporate into our application.
diff --git a/docs/_dg/Implementation.md b/docs/_dg/Implementation.md
@@ -24,3 +24,7 @@ There are four main groups of features that are implemented:
 ### General Features
 
 {% include_relative _dg/implementations/GeneralFeatures.md %}
+
+### User Interface
+
+{% include_relative _dg/implementations/UserInterface.md %}
diff --git a/docs/_dg/UIComponent.md b/docs/_dg/UIComponent.md
@@ -7,7 +7,7 @@ The UI component handles the user-interface portion of the application.
 
 The UI consists of a `MainWindow` that is made up of parts, e.g.`CommandBox`, `ResultDisplay`, `ItemListPanel`, `StatusBarFooter` etc. All these, including the `MainWindow`, inherit from the abstract `UiPart` class which captures the commonalities between classes that represent parts of the visible [[ graphical-user-interface:GUI ]].
 
-The `UI` component uses the JavaFx UI framework. The layout of these UI parts is defined in matching `.fxml` files that are in the `src/main/resources/view` folder. For example, the layout of the [MainWindow]({{ page.master_branch }}/{{ page.main_src }}/ui/MainWindow.java) is specified in [MainWindow.fxml]({{ page.master_branch }}/src/main/resources/view/MainWindow.fxml)
+The `UI` component uses the JavaFX UI framework. The layout of these UI parts is defined in matching `.fxml` files that are in the `src/main/resources/view` folder. For example, the layout of the [MainWindow]({{ page.master_branch }}/{{ page.main_src }}/ui/MainWindow.java) is specified in [MainWindow.fxml]({{ page.master_branch }}/src/main/resources/view/MainWindow.fxml)
 
 The `UI` component,
 

diff --git a/docs/_dg/implementations/GeneralFeatures.md b/docs/_dg/implementations/GeneralFeatures.md
@@ -5,10 +5,12 @@
 <!-- TODO: ADD GENERAL FEATURES CLASS DIAGRAM -->
 <!-- NOTE: As this is for general features like Help, add/remove class diagrams as you see fit -->
 
-The `Exit command` and `Reset command` do not contain complex implementations. 
+The `Exit command` and `Reset command` do not contain complex implementations.
+
+Exit command returns a `CommandResult` that returns `true` when calling the method `shouldExit()` on it.
+
+The reset command functions like most other commands.
 
-Exit command returns a `CommandResult` that returns `true` when calling the method `shouldExit()` on it. 
-The reset command functions like most other commands. 
 The `HelpCommand` is worth looking into, as it involves opening a separate window (`HelpWindow`).
 
 #### Displaying Help Dialogs

diff --git a/docs/_dg/implementations/UserInterface.md b/docs/_dg/implementations/UserInterface.md
@@ -0,0 +1,48 @@
+<!-- markdownlint-disable-file first-line-h1 -->
+#### General Implementation Details
+
+FoodRem's User Interface or UI (more specifically, it is a [[ graphical-user-interface:GUI ]]) consists of a main window and the Help Window. In this section, we will focus on the main window only, specifically, the Command Output Box component of the main window and its use of the "views", "models" and "view models".
+
+#### General Design Considerations
+
+The main window comprises of three components: the [[ command-input-box:Command Input Box ]] and [[ item-list-box:Item List Box ]] on the left half of the main window, as well as the [[ command-output-box:Command Output Box ]] on the right half. For the Command Input Box, it only needs to render the same component each time in order to provide a text field for the user to type their commands into. Likewise, for the Item List Box, it only needs to render a list each time. While the number of items in the list may be variable, it is still the same component to render the list (specifically, it is JavaFX's `ListView` component). This means that when a command is executed, any UI updates to these first two components can be achieved relatively easily.
+
+However, the Command Output Box needs to be able to have potentially different rendered views to be shown to the user, depending on what command was run. This is where the "views", "models" and "view models" come in. They are clarified as follows:
+
+* "Views" return a JavaFX `Node` object in order to place into the Command Output Box
+* "Models" represent data entities used in FoodRem. See the [Model Component](#model-component) section above for more information. The "models" that are concerned in the process of rendering outputs to the GUI are [[ item:items ]] and [[ tag:tags ]].
+* "View models" are not always present, and act as a bridge for when the data contained in a single "model" is not enough for the corresponding "view" to be generated. As a "view" can only be generated from a single "view model", when data from one or more "models" need to be processed and/or augmented before a "view" can be generated, the "view model" acts as a bridge to facilitate the process.
+
+#### Rendering Command Output
+
+[`UiView`]({{ page.master_branch }}/{{ page.main_src }}/views/UiView.java) is the main class responsible for rendering the view to the Command Output Box. This is achieved when a caller calls `UiView`'s `viewFrom` method. The method then calls the `from` method of one of nine "views", depending on the type of the object that was requested to be rendered.
+
+The nine "views" are as follows:
+
+| Class Name                                                                                           | Description                                                                                                                                                                   |
+|------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [`FilterByTagView`]({{ page.master_branch }}/{{ page.main_src }}/views/FilterByTagView.java)         | A view resulting from the `filtertag` command.                                                                                                                                |
+| [`ItemView`]({{ page.master_branch }}/{{ page.main_src }}/views/ItemView.java)                       | A view resulting from the `view` command, as well as a generic view for items which may be used elsewhere.                                                                    |
+| [`ItemWithMessageView`]({{ page.master_branch }}/{{ page.main_src }}/views/ItemWithMessageView.java) | A generic view of an item with a single message above it. This view results from the  `dec`, `del`, `edit`, `inc`, `new`, `rmk`, `tag` and `untag` commands.                  |
+| [`StatsView`]({{ page.master_branch }}/{{ page.main_src }}/views/StatsView.java)                     | A view resulting from the `stats` command.                                                                                                                                    |
+| [`StringView`]({{ page.master_branch }}/{{ page.main_src }}/views/StringView.java)                   | A generic view for a string message. This view is used to display command errors, as well as the outputs of the `exit`, `help`, `reset`, `find`, `list`, and `sort` commands. |
+| [`TagToRenameView`]({{ page.master_branch }}/{{ page.main_src }}/views/TagToRenameView.java)         | A view resulting from the `renametag` command.                                                                                                                                |
+| [`TagView`]({{ page.master_branch }}/{{ page.main_src }}/views/TagView.java)                         | A generic view for a [[ tag:Tag ]]. Used in other views to ensure consistency of how a Tag looks like.                                                                        |
+| [`TagsView`]({{ page.master_branch }}/{{ page.main_src }}/views/TagsView.java)                       | A generic view for multiple [[ tag:tags ]], for use in other views.                                                                                                           |
+| [`TagsWithMessageView`]({{ page.master_branch }}/{{ page.main_src }}/views/TagsWithMessageView.java) | A view of some tag(s) with a message above them. This view results from the `deletetag`, `listtag` and `newtag` commands.                                                     |
+
+The individual "view" is responsible to generate the JavaFX `Node` structure to be placed into the Command Output Box. This node structure is then placed by `UiView`.
+
+A sequence diagram of this process is as follows:
+
+![](images/UISequenceDiagram.png)
+
+```note
+The above sequence diagram assumes the caller requested a `String` to be rendered.
+```
+
+##### Future Extensions
+
+Currently, `UiView` uses a very hacky method to determine the type of the object that was requested to be rendered; it uses consecutive `instanceof` expressions. Ideally, there should be a common interface where the necessary operations required can be achieved through dynamic binding. A possible class diagram is as follows:
+
+![](images/UIProposedClassDiagram.png)
diff --git a/docs/_ug/TryingFirstCommand.md b/docs/_ug/TryingFirstCommand.md
@@ -84,7 +84,7 @@ You should now have a better understanding of how commands are formatted and use
 
 Here is a checklist you can use before running a [[ command ]]:
 
-* [ ] I know the restrictions of the command 
+* [ ] I know the restrictions of the command
 * [ ] I know what [[ parameter:parameters ]] are supplied to the command
 * [ ] I know the [[ flag:flags ]] for each parameter to be supplied
 * [ ] I know the restrictions of each parameter

diff --git a/docs/diagrams/UIProposedClassDiagram.puml b/docs/diagrams/UIProposedClassDiagram.puml
@@ -0,0 +1,33 @@
+@startuml
+!include style.puml
+skinparam arrowThickness 1.1
+skinparam arrowColor UI_COLOR_T4
+skinparam classBackgroundColor UI_COLOR
+
+Class "<<interface>>\nViewable" as Viewable
+
+Class FilterByTagView
+Class ItemView
+Class ItemWithMessageView
+Class StatsView
+Class StringView
+Class TagToRenameView
+Class TagView
+Class TagsView
+Class TagsWithMessageView
+
+FilterByTagView ..|> Viewable
+ItemView ..|> Viewable
+ItemWithMessageView ..|> Viewable
+StatsView ..|> Viewable
+StringView ..|> Viewable
+TagToRenameView ..|> Viewable
+TagView ..|> Viewable
+TagsView ..|> Viewable
+TagsWithMessageView ..|> Viewable
+
+Class UiView
+
+Viewable -- UiView
+
+@enduml
diff --git a/docs/diagrams/UISequenceDiagram.puml b/docs/diagrams/UISequenceDiagram.puml
@@ -0,0 +1,15 @@
+@startuml
+!include style.puml
+
+[-> UiView : viewFrom("hello")
+activate UiView
+
+UiView -> StringView : from("hello")
+activate StringView
+
+UiView <-- StringView
+deactivate StringView
+
+[<--UiView
+deactivate UiView
+@enduml
diff --git a/docs/images/UIProposedClassDiagram.png b/docs/images/UIProposedClassDiagram.png
diff --git a/docs/images/UISequenceDiagram.png b/docs/images/UISequenceDiagram.png
diff --git a/docs/team/ferusel.md b/docs/team/ferusel.md
@@ -14,10 +14,10 @@ Given below are my contributions to the project.
 
 * **New Feature**: Statistics feature
 
-  * What it does: Calculates some statistics regarding the Items and Tags in FoodRem's inventory, and displays them to the user. Statistics include: Top three most commonly used tags, top three most expensive items in inventory, total cost accrued due to food waste. 
-  * Highlights: These statistics were chosen after discussion as they were determined to be most useful and provided a high degree of flexibility. It was not easy to choose the statistics. 
+  * What it does: Calculates some statistics regarding the Items and Tags in FoodRem's inventory, and displays them to the user. Statistics include: Top three most commonly used tags, top three most expensive items in inventory, total cost accrued due to food waste.
+  * Highlights: These statistics were chosen after discussion as they were determined to be most useful and provided a high degree of flexibility. It was not easy to choose the statistics.
   * Credits: N/A
-   
+
 * **New Feature**: `Item` class
 
   * What it does: Provides an internal representation of an `Item` in FoodRem. Adapted from the original AB3's `Person` class, I laid the foundation by adding the necessary attributes to represent an `Item`. I also wrote test cases for the `Item` class.
@@ -28,7 +28,7 @@ Given below are my contributions to the project.
 * **New Feature**: `inc`, `dec`, `view` commands
 
   * What it does: `inc` allows the user to increment a chosen item by a specified quantity. `dec` allows the user to decrement a chosen item by a specified quantity. `view` displays all relevant information about an `Item`, such as the quantity, name, tags, to the user.
-  * Justification: These are key features for FoodRem. 
+  * Justification: These are key features for FoodRem.
 
 * **New Feature**: `sort` command
 
@@ -58,26 +58,26 @@ Given below are my contributions to the project.
     * Improve UG for v1.3 [[PR#335]]
     * Fix UG after Peer Review [[PR#351]]
     * Fix find command description in Command Summary [[PR#324]]
-   
+
   * Developer Guide:
     * Add Glossary, UC3, UC4 to Developer Guide [[PR#87]]
     * Add Glossary section to Developer Guide [[PR#164]]
     * Add Sorting user stories to DG [[PR#210]]
     * Add Sort Command UML [[PR#232]]
     * Update Developer Guide with v1.3  [[PR#295]]
 
-* ** Features**:
+* **Features**:
   * Add Item model [[PR#143]]
   * Add Sort Command [[PR#158]]
   * Add Increment and Decrement Command [[PR#161]]
   * Add View command [[PR#209]]
   * Add Statistics Command [[PR#360]]
   * Update find command [[PR#367]]
   * Fix stats command [[PR#372]]
- 
+
 * **Community**:
 
-  * Created [forum discussion](https://github.com/nus-cs2103-AY2223S1/forum/issues/413) 
+  * Created [forum discussion](https://github.com/nus-cs2103-AY2223S1/forum/issues/413)
 
 * **Misc PRs**:
   * Add profile picture [[PR#67]]
Original file line number	Diff line number	Diff line change
Expand Up		@@ -9,4 +9,4 @@ One challenge we ran into during the project was implementing a batch feature fo

		### Revamping of UI

		We wanted a simple yet appealing [[ graphical-user-interface:graphical user interface ]] for our application's users. As such, we decided to change the original UI of AB3 into our own new FoodRem UI. As our team was not familiar with JavaFX initially, it took us considerable time and effort to produce an eventual satisfactory and working UI that we were proud to adopt and incorporate into our application.
		We wanted a simple yet appealing [[ graphical-user-interface:graphical user interface ]] for our application's users. As such, we decided to change the original UI of AB3 into our own new FoodRem UI. As our team was not familiar with JavaFX initially, it took us considerable time and effort to produce an eventual satisfactory and working UI that we were proud to adopt and incorporate into our application.