JelphaBot - Developer Guide

To use the different features, we have also implemented commands for users to switch between the 5 tabs.

Each respective shortcut also has the respective letter bolded in the Tab Panel of the User Interface. Shortcuts are case insensitive.

Tab changing in the application is defined using a SwitchTab enumeration. Tab changes are called at the end of a command by reading the private attribute toSwitch in CommandResult. To initiate a tab switch, the Command which returns the CommandResult with the corresponding value of toSwitch, set with the method isShow{tabLabel}, where {tabLabel} refers to the name of the tab defined in SwitchTab.

When the tab of the application is changed, we need to update the:

As an example, the figure below shows the sequence diagram of when a user executes the :s or summary command.

Upon execution of the :s command, SummaryCommand#generateCommandResult() will generate a CommandResult whose SwitchTab attribute is set to SUMMARY and return it to the LogicManager. Upon execution of the :s command, SummaryCommand#generateCommandResult() will generate a CommandResult whose SwitchTab attribute is set to SUMMARY and return it to the LogicManager. Now, the updates can be done for the respective components:

The implementation of this panel is facilitated by the summary package.

Upon creation, the Summary object obtains the main task list from Model. The task list is then filtered with the help of TaskDueWithinDayAndIncompletePredicate and TaskCompletedWithinDayPredicate to obtain two lists with the desired tasks.

These lists are stored as fields in the Summary class and are used to display the relevant information in the summary panel.

The following class diagram shows the structure of the classes in the summary package, in relation with their Ui counterparts.

To view the respective tasks, the user enters the summary command. Upon entry of the summary command, a SummaryCommand object will be created and SummaryCommand#execute() will be called.

The following sequence diagram details the execution when SummaryCommand#execute() is called.

The task category mechanism is facilitated by the ViewTaskList interface, which serves as a wrapper for any list of tasks.
The ViewTaskList interface supports methods that facilitate getting and iterating through the tasks contained within the list. This is to accommodate a common access for Tasks in GroupedTaskList, which contains multiple sub-lists.
The diagram below describes the class structure.

Grouping tasks into sub-lists is done through the GroupedTaskList class.
Each GroupedTaskList is a container for ObservableList<Task> objects, each containing a unique filter over the full task list.

Each GroupedTaskList implements the following operations on top of those in ViewTaskList:

Users can modify the GroupTaskList being displayed in the main panel by executing a ListCommand. The operation for retrieving the corresponding GroupedTaskList is exposed in the Model interface as Model#getGroupedTaskList(Category category).
Currently, the supported groupings for JelphaBot are group by date (GroupedTaskList.Category.DATE and GroupedByDateTaskList) and group by module (GroupedTaskList.Category.MODULE and GroupedByModuleTaskList).

The following diagram shows the sequence flow of a ListCommand which modifies the currently shown Task List:

Given below is an example usage scenario and how the task category mechanism behaves at each step.

Step 1. The user launches the application for the first time. The MainWindow will be initialized with GroupedTaskListPanel as a container for GroupedTaskList model objects. The panel is populated with sublists defined in GroupedByDateTaskList.

Step 2. The user executes list model to switch to category tasks by module code instead. GroupedTaskListPanel is repopulated with sublists defined in GroupedByModuleTaskList.

As GroupedTaskList has more than one underlying ObservableList<Task>, tasks cannot be retrieved the usual way. Thus, the get() function defined in the ViewTaskList interface must be implemented and used instead.
The following diagram shows the process of retrieving a Task from ViewTaskList when it is an instance of GroupedTaskList:

As the index passed as an argument to lastShownList.get() is a cumulative index, the implementation of get() in ViewTaskList has to iterate through each SubgroupTaskList stored within.

Tasks are organized via a two-dimensional list. In this case, a Task is rendered into a TaskCard, and TaskCard elements are rendered within SubGroupTaskListCell elements which are listed in SubgroupTaskListPanel. A populated SubgroupTaskListPanel element is rendered as a GroupedTaskListCell which is listed in the top-level GroupedTaskListCell.
SubgroupTaskListCell and GroupedTaskListCell implement the ListViewCell<T> interface of the ListView<T> class provided by JavaFX.

The detailed interactions are described in the diagram shown above. As can be seen, the distribution of ListViewCell elements follows the way tasks are distributed within the model classes. Each SubgroupTaskListPanel is displaying a singular SubgroupTaskList, which further contains a list of Task entities.

The indexes displayed in each TaskCard is dynamically computed from a NumberBinding which computes the index of that element in the list. The NumberBinding observes the place of the task within the current SubgroupTaskList as well as the number of elements in the preceding sublists. The sum of both numbers gives the index for the current element, which is set using setId(). TaskCard elements are updated with populateTaskElements().

Each TaskCard will also have a different visual presentation depending on the value of the Priority of the task. The method which adjusts the visual presentation of a Task is applyPriorityMarkdown().

The following images show how Task entities of different priorities are displayed:

The implementation of the main calendar panel is facilitated by the CalendarMainPanel class, which serves as the main container for this feature. This main container consists of a SplitPane comprising of a CalendarPanel on the right, which displays the calendar view in a month, and a CalendarTaskListPanel on the left to display specific tasks.

The diagram below describes the class structure of the calendar class structure.

Upon initialisation of the CalendarMainPanel, the CalendarPanel would be set to display the current month and year calendar, with the dates filled up by CalendarDayCard by CalendarPanel#fillGridPane() with a CalendarDate starting from the first day of the current month. Today’s date would also be highlighted, with CalendarTaskListPanel set to display the tasks due today by running Logic#getFilteredCalendarTaskList() and then Logic#updateFilteredCalendarTaskList() with a predicate to filter by today’s date.

The following diagram depicts how each individual day cell of the calendar will look like:

After every execution of command, MainWindow#updateTasksInCalendarDayCards() will be run such that any commands that updates the JelphaBot task list (e.g DoneCommand, DeleteCommand, EditCommand) would be updated by the dot indicators in the calendar.

Function 1: Displays an overview of tasks in calendar for a selected month and year

There are 2 commands that users can issue to perform function 1:

Upon execution of the calendar MONTHYEAR or the calendar today command, CalendarCommand#execute() will run updateFilteredCalendarTaskList() to filter the task list to display the tasks on the CalendarTaskListPanel according to the first day of the MONTHYEAR or the tasks due today respectively. The filtering of the tasks according to date is done using the TaskDueWithinDayPredicate. A distinct CommandResult would then be generated according to the input command and is returned to the LogicManager. Finally, the CommandResult is passed to the MainWindow in UI. Now, the updates can be done for the respective components:

UI Component: Using the CommandResult, MainWindow calls MainWindow#updateCalendarMainPanel(), which is then passed to call CalendarMainPanel#updateCalendarPanel(). For the calendar MONTHYEAR command, this updates the CalendarPanel display with the respective MONTHYEAR view, and highlights the first day of the month. For the calendar today command, this updates the CalendarPanel display to the current month and year, with today’s date highlighted.

The following example sequence diagram shows you how the calendar MONTHYEAR (e.g. calendar Apr-2020) command works.

Function 2: Display a list of tasks due for a selected date in the month

In order to display the task list for specific input dates, the user enters the calendar DATE command
(e.g. calendar Jan-1-2020).

The implementation of the previous two calendar commands (calendar DATE and calendar today) are largely similar and run in the same process. The only exception is regarding the calendar DATE command which fulfills Function 2 listed above, where the GridPane in CalendarPanel is not altered by running CalendarPanel#fillGridPane() unlike the other two commands fulfilling Function 1. Only CalendarTaskListPanel is updated.

The following diagram shows the sequence flow for variants of these three calendar commands which modifies the CalendarMainPanel:

Text rendered onto the productivity panel is retrieved from the Productivity class.
A Productivity object is a container for the objects responsible for the sub-parts of the panel, namely TimeSpentToday, RunningTimers and TasksCompleted. Each of these have their respective String representations which will be used in rendering the panel.

TimeSpentToday implements the following operations:

RunningTimers implements the following operations:

TasksCompleted implements the following operations:

Information from all three objects are subsequently rendered onto the panel through ProductivityCard and ProductivityPanel.

Assuming that the task list is not empty, the following describe the flow of start 1 and stop 1 which modify the currently shown productivity panel:

Function 1: Starts timer for a specified task
In order to start timing a task, the user enters start INDEX command (e.g. start 1).

Upon successful execution of the command, the productivity tab displays the task being timed under the Running Timer(s) header. The following diagram shows the flow of start 1 which modifies the current view of the productivity panel:

To update the productivity panel to reflect the changes, a new Productivity object will first be created, replacing the existing Productivity object in the ProductivityList. Each time a new Productivity object is created, its corresponding booleans will dictate whether the sub-parts (i.e. TimeSpentToday, RunningTimers and TasksCompleted) are to be replaced with new objects. As the command executed is start, a new RunningTimers object is created. As detailed above, the iterator method in RunningTimers will be called and a new String representation to be displayed onto the productivity panel will be created. This String is subsequently rendered onto the panel under the Running Timer(s) header.

The following diagram shows the flow which updates the Running Timer(s) section in the productivity panel:

Function 2: Stops timer for a specified task
In order to stop timing a task, the user enters stop INDEX command (e.g. stop 1)

Upon successful execution of the command, the productivity tab removes the task being timed under the Running Timer(s) header. Removing a task from the Running Timer(s) header is similar to adding it, as illustrated by the Activity Diagram above. Under the Time Spent header, the total time spent will be increased in the respective subheaders depending on the date that the task is due.

The Reminder feature was implemented by a new set of classes to Model. A new Reminder class is stored in Jelphabot’s UniqueReminderList, which consists of a list of Reminder s. Each Reminder consists of 3 objects:
Index: the Task 's index of which the user wants to be reminded for.
ReminderDay: the number of days before the Task 's deadline that the user wants to be reminded for.
ReminderHour: the number of hours before the Tasks 's deadline that the user wants to be reminded for.

The following class diagram summarizes shows the relationship between the classes.

Function 1: Creates a reminder for a specified task
To add a reminder to a certain task, the user enters the reminder INDEX days/DAYS hours/HOURS command. (e.g, reminder 2 days/2 hours/1)

The Logic execute() method creates a ReminderCommand from the input string by parsing the input according to the command word and several other attributes. Next, the input string is converted into Index, ReminderDay, ReminderHour, and a Reminder object with these properties are forwarded to Model.

The Model first checks the validity of the attributes respectively. The valid Reminder is then added to the UniqueReminderList after checking that there are no other Reminder with the same Index.

After the above actions are correctly performed, the Logic fires the Storage to save the Reminder.

Upon successful execution of the command, the user adds a reminder associated to the task at INDEX. Upon exiting JelphaBot, the reminder will be saved. By the next time the users starts JelphaBot, it will remind the user should the task’s due date fall within the period set by the user from the current date.

The sequence diagram for interactions between the Logic, Model, and Storage is shown below.

Function 2: Deletes a reminder for a specified task
To delete a reminder associated to a certain task, the user enters the delrem INDEX command. (e.g. delrem 2)

The interaction between components is similar to adding a Reminder. A key difference that this command removes the Reminder that reminds the Task at INDEX from the UniqueReminderList. Moreover, delrem command requires that the Reminder with INDEX is in the list.

Upon successful execution of the command, the reminder of the task at INDEX is removed.

The undo/redo mechanism is facilitated by VersionedJelphaBot. It extends JelphaBot with an undo/redo history, stored internally as a jelphaBotStateList and currentStatePointer. Additionally, it implements the following operations:

These operations are exposed in the Model interface as Model#commitJelphaBot(), Model#undoJelphaBot() and Model#redoJelphaBot() respectively.

Given below is an example usage scenario and how the undo/redo mechanism behaves at each step.

Step 1. The user launches the application for the first time. The VersionedJelphaBot will be initialized with the initial JelphaBot state, and the currentStatePointer pointing to that single JelphaBot state.

Step 2. The user executes delete 5 command to delete the 5th task in JelphaBot. The delete command calls Model#commitJelphaBot(), causing the modified state of JelphaBot after the delete 5 command executes to be saved in the jelphaBotStateList, and the currentStatePointer is shifted to the newly inserted JelphaBot state.

Step 3. The user executes add d/Assignment …​ to add a new task. The add command also calls Model#commitJelphaBot(), causing another modified JelphaBot state to be saved into the jelphaBotStateList.

Step 4. The user now decides that adding the task was a mistake, and decides to undo that action by executing the undo command. The undo command will call Model#undoJelphaBot(), which will shift the currentStatePointer once to the left, pointing it to the previous JelphaBot state, and restores JelphaBot to that state.

The following sequence diagram shows how the undo operation works:

The redo command does the opposite — it calls Model#redoJelphaBot(), which shifts the currentStatePointer once to the right, pointing to the previously undone state, and restores JelphaBot to that state.

Step 5. The user then decides to execute the command list. Commands that do not modify JelphaBot, such as list, will usually not call Model#commitJelphaBot(), Model#undoJelphaBot() or Model#redoJelphaBot(). Thus, the jelphaBotStateList remains unchanged.

Step 6. The user executes clear, which calls Model#commitJelphaBot(). Since the currentStatePointer is not pointing at the end of the jelphaBotStateList, all JelphaBot states after the currentStatePointer will be purged. We designed it this way because it no longer makes sense to redo the add n/Assignment …​ command. This is the behavior that most modern desktop applications follow.

The following activity diagram summarizes what happens when a user executes a new command: