Developer Guide
Calidr is a time-management and scheduling calendar application, optimized for use via a Command Line Interface ( CLI) while still having the benefits of a Graphical User Interface (GUI). This application uses the AddressBook-Level3 project created by the SE-EDU initiative as its framework.
Implementation
This section describes how certain components and features are implemented.
Calendar Panel
The CalendarPanel
is the component that displays the calendar graphically, featuring several calendar formats. It is
read-only,
extends AB3’s UIPart
, replaces PersonListPanel
and is implemented using the
open-source CalendarFX framework.
The CalendarPanel
is instantiated in MainWindow
with a DateControl
object. The TaskEntry
class encapsulates all
the information of a task, including its description, date, time and tags; by extending the Entry
class of CalendarFX,
it is able to be displayed on the DateControl
object.
CalendarPanel
implements the following operations:
updateCalendar(taskList)
— Updates theCalendarView
object with aReadOnlyTaskList
.showInformationDialog(entry)
— Spawns a dialog box with additional information of aTaskEntry
.setDate(date)
,goToToday()
,goToNext()
,goToPrevious()
— Operations which change the date (or month) shown by theCalendaraPanel
. The default date on startup is the current date.setPage(view)
,nextPage()
, — Changes the page (layout) of theCalendarPanel
to aDAY_VIEW
,WEEK_VIEW
orMONTH_VIEW
. The default view on startup isMONTH_VIEW
.
The CalendarPanel
holds three DateControl
objects, each representing a different view of the calendar. Only one is
visible and managed by the CalendarPanel
at any given time, and it is possible to switch between the three views.
Event
and ToDo
-derived TaskEntry
s are each held in two different Calendar
objects, so that they can be styled
differently.
The CalendarPanel
is updated by calling updateCalendar(taskList)
with a ReadOnlyTaskList
object. This method is
invoked by MainWindow
after a command is executed.
Below is a sequence diagram of the updateCalendar(taskList)
operation:
Add ToDo Feature
This feature enables the user to add a to-do to the list of tasks. It is implemented in a way that mirrors the Add Person feature in AB3.
The following class diagram shows the classes that help achieve this functionality.
The AddTodoCommandParser
parses the required details, to create the ToDo
to be added, and returns
an AddTodoCommand
, that is executed.
The execution of an AddTodoCommand
makes use of the following functions provided by the Model
:
Model#hasTask
- to prevent duplication of a to-doModel#addTask
- to add theToDo
to theUniqueTaskList
The following sequence diagram shows how the Add ToDo feature works.
Design Considerations
The Add ToDo feature is implemented in this way so as to make it similar to the analogous Add Person feature of AB3. Since Calidr uses the same overall architecture as AB3, such an implementation was chosen.
Add Event Feature
This feature enables the user to add an event to the list of tasks. It is implemented in a way that mirrors the Add Person feature in AB3.
The following class diagram shows the classes that help achieve this functionality.
The AddEventCommandParser
parses the required details, to create the Event
to be added, and returns
an AddEventCommand
, that is executed.
The execution of an AddEventCommand
makes use of the following functions provided by the Model
:
Model#hasTask
- to prevent duplication of an eventModel#addTask
- to add theEvent
to theUniqueTaskList
The following sequence diagram shows how the Add Event feature works.
Design Considerations
The Add Event feature is implemented in this way so as to make it similar to the analogous Add Person feature of AB3. Since Calidr uses the same overall architecture as AB3, such an implementation was chosen.
Edit task feature
The EditTaskCommand
class represents a command that edits an existing task. It takes in the index of the task in
the task list to be edited and an EditTaskDescriptor
object.
The following class diagram shows the classes that help achieve this functionality.
The EditTaskCommandParser
class parses the fields entered by the user in the correct format, and returns a
EditTaskCommand
to be executed. The EditTaskDescriptor
class is a helper class that stores the new details of the
task to be updated. The EditTaskCommand::execute
method updates the task in the model with the new details and returns
a CommandResult
.
The relevant information is used to create a new Todo
or Event
object with the updated fields. The newly created
object replaces the task to be edited in the TaskList
. Finally, an output is displayed with the status of the edit
operation and the updated task details.
Design considerations:
Aspect: How edit command executes
- Alternative 1 (current choice): Overwrite all existing task fields if any of them is modified.
- Pros: Easy to implement.
- Cons: Might be inefficient in terms of resource usage and possibly cause delays
- Alternative 2: Only update the task fields that were changed.
- Pros: Will use less resources and time, thus improving system performance.
- Cons: Requires more complex implementation logic to track and update the modified fields.
Mark Task Feature
The MarkTaskCommand
class represents a command that marks an existing task as done. It takes in the index of the
task in the task list to be marked and returns a CommandResult
.
The following class diagram shows the classes that help achieve this functionality.
The MarkTaskCommandParser
parses the required index to find the Task
to be deleted, and returns
a MarkTaskCommand
, that is executed.
The execution of an MarkTaskCommand
makes use of the following functions provided by the Model
:
Model#getFilteredTaskList
- to access the list of tasks, to find the task to be markedModel#markTask
- to mark theTask
int theTaskList
as done
The following sequence diagram illustrates how the Mark Task feature works.
Delete Task Feature
This feature enables the user to delete a task from the list of tasks. It is implemented in a way that mirrors the Delete Person feature in AB3.
The following class diagram shows the classes that help achieve this functionality.
The DeleteTaskCommandParser
parses the required details, to find the Task
to be deleted, and returns
a DeleteTaskCommand
, that is executed.
The execution of an DeleteTaskCommand
makes use of the following functions provided by the Model
:
Model#getFilteredTaskList
- to access the list of tasks, to find the task to be deletedModel#deleteTask
- to delete theTask
from theUniqueTaskList
The following sequence diagram shows how the Delete Task feature works.
Design Considerations
The Delete Task feature is implemented in this way so as to make it similar to the analogous Delete Person feature of AB3. Since Calidr uses the same overall architecture as AB3, such an implementation was chosen.
Search Feature
This feature enables the user to search for specific tasks using keywords. It is implemented in a way that mirrors the Find Person feature in AB3.
The following class diagram shows the classes that help achieve this functionality.
The SearchTaskCommandParser
parses the required details - keywords to search for Task
’s by, and returns
a SearchTaskCommand
, that is executed.
The execution of an SearchTaskCommand
makes use of the following functions provided by the Model
:
Model#updateFilteredTaskList
- to apply the keywords filter on the list of tasksModel#getFilteredTaskList
- to access the filtered list of tasks
The following sequence diagram shows how the Search feature works.
Design Considerations
The Search feature is implemented in this way so as to make it similar to the analogous Find Person feature of AB3. Since Calidr uses the same overall architecture as AB3, such an implementation was chosen.
Storage Feature
The Storage Feature handles the below requirements:
- Saves user preference data in json format, and task list items (events, todos) in ics format
- To abstract over ics files, we use the ical4j library as a intermediate layer.
- It depends on the classes in the Model component
Planned Enhancements
- The base Calendar GUI leaves much to be desired. We plan to implement a more user-friendly GUI, where the calendar entries are color-coded according to priority and status, instead of being expressed textually, to workaround text-wrapping.
- We plan to implement a more robust search function, where the user can search for tasks by details other than the title, such as the description, priority, and tags.
- We’re looking to give users the option of whether they want tasks to overlap or clash. The current implementation assumes that tasks can overlap.
Appendix
Requirements
Target User Profile
- NUS staff or student
- prefer desktop apps over other types
- can type fast
- prefers typing to mouse interactions
- is reasonably comfortable using CLI apps
Value Proposition
- Text-based timetable management
- Add todos and events
- Add reminders to todo/event
- Search
- /view day
- /view month
User Stories
As a … | I want to … | So that I can … | Priority |
---|---|---|---|
NUS staff/student | add my classes and todos to my calendar | keep track of my daily schedule. | High |
NUS staff/student | add a title to an event/todo during it’s creation | distinguish events/todos | High |
NUS staff/student | import/export my calendar as an iCalendar (.ics ) file |
save it as an offline copy | High |
NUS student | set notifications for upcoming exams and assignments | not forget to complete them on time. | High |
NUS student with a busy schedule | view my calendar in different views (daily, weekly, monthly) | get a comprehensive view of my schedule. | Mid |
NUS staff/student | search/sort for todos <ul><li>by description</li><li>by a range of dates</li><li>by recency</li></ul> | <ul><li>look for specific or related todos for editing</li><li>check my availability during holidays/exam weeks</li><li>identify todos with higher priority</li></ul> | High |
NUS staff/student | set (during creation) the duration for a certain event | manage todos that occur over a span of time. | High |
NUS staff/student | change the duration of a event after its creation | make changes if I make mistakes | Mid |
NUS staff/student | set tags on events and todos | easily find them again | Mid |
NUS staff/student | add a priority to todo | keep track of them easily | Mid |
NUS staff/student | be able to change the name of a event/todo after its creation | - | Low |
NUS staff/student | set a recurrence for a todo/event | save time on repeating todos | Low |
NUS staff/student | keep track of my todos in a list | refer to them in a convenient fashion | High |
NUS staff/student | add notes or comments to each event in my calendar | note down non-critical but useful information. | Low |
NUS staff/student | be able to add a description to a todo/event | keep track of additional details | High |
NUS staff/student | add an optional location to my todos | record specific addresses if it is a place I need to be. | Low |
Use Cases
(For all use cases below, the System is Calidr and the Actor is the user, unless specified otherwise)
Change the duration of an event
MSS
- User requests to list events
- Calidr shows a list of events
- User requests to query a specific event in the list by index and overwrite the date fields with a new value
- Calidr modifies and saves the new dates for the event. Use case ends.
Extensions
- 2a. The list is empty. Use case ends.
- 3a. The given index is invalid.
- 3a1. Calidr shows an error message. Use case resumes at step 2.
Non-functional requirements
- Should work on any mainstream OS (in particular file I/O) with Java 11 installed.
- Should be able to manage 1000 items without a noticeable sluggishness in performance for typical usage.
- A user with above average typing speed for regular English text (i.e. not code, not system admin commands) should be able to accomplish most of the todos faster using commands than using the mouse.
Glossary
- Mainstream OS: Windows, Linux, Unix, OS-X
- Tasks: Elements on a calendar. a. ToDos: Items with a single associated date-time (e.g. a due date) and status (done or not done). b. Events: Items with two associated date-times.