Skip to content

Latest commit

 

History

History
589 lines (444 loc) · 18.4 KB

UserGuide.adoc

File metadata and controls

589 lines (444 loc) · 18.4 KB
Raw

Cow - User Guide

By: Team T09-1      Since: Aug 2018      Licence: MIT

1. Introduction

Cow is an application for those who prefer to use a desktop app for managing tasks and contacts. It is optimized for those who prefer to work with a Command Line Interface (CLI) while still having the benefits of a Graphical User Interface (GUI). If you can type fast, Cow can get your contact and task management done faster than traditional GUI apps.

2. Quick Start

  1. Ensure you have JRE 9 or later installed.

  2. Download the latest .jar file here.

  3. Place it in the folder where you want the data files to be stored.

  4. Double-click the .jar file to start the app. The GUI should appear in a few seconds

    Ui

  5. Type in a command and press Enter to execute it. For a start, type help and press Enter to see the help page.

  6. Some example commands you can try:

    • contacts list : lists all contacts

    • contacts add n/John Doe p/98765432 e/[email protected] a/311, Clementi Ave 2, #02-25 t/friends t/owesMoney: adds contact named John Doe to Cow

    • tasks list : lists all tasks

    • tasks delete 2 : deletes the 2nd task shown in the list

    • exit : exits Cow

Warning
 Ensure that your screen resolution is at least 1920x1080, or the calendar might not show properly.

3. Features

Command Format

  • Words in UPPER_CASE are the parameters to be supplied by the user e.g. in contacts add n/NAME, NAME is a parameter which can be used as contacts add n/John Doe.

  • Items in square brackets are optional e.g n/NAME [t/TAG] can be used as n/John Doe t/friend or as n/John Doe.

  • Items with … after them can be used multiple times including zero times e.g. [t/TAG]…​ can be used as \ (i.e. 0 times), t/friend, t/friend t/family etc.

  • Parameters can be in any order e.g. if the command specifies n/NAME p/PHONE_NUMBER, p/PHONE_NUMBER n/NAME is also acceptable.

💡
 When INDEX is a parameter, it refers to the index of the item shown on the task or person list.
ℹ️
 Don’t worry about having friends or tasks with the same name — just add them and Cow will process them correctly.

3.1. Viewing help: help

Format: help

💡
 Besides this help page, running a command with the wrong format will also show you how to use the command properly.
ℹ️
 The help page will be shown in another window, but you can resize and move it around. This can be useful to refer to when using the app.

3.2. Contacts

ℹ️
 You are allowed to have entries with the same name.

3.2.1. View all contacts: contacts list

Shows a list of all people in Cow.
Format: contacts list

3.2.2. Add contact: contacts add

Adds a person to Cow.
Format: contacts add n/NAME p/PHONE_NUMBER e/EMAIL a/ADDRESS [t/TAG]…

💡
 A person can have any number of tags (including 0).

Examples:

  • contacts add n/John Doe p/98765432 e/[email protected] a/1 Cow Ave, #02-25 t/intern

  • contacts add n/Jane Smith p/92948232 e/[email protected] a/10 Cow Boulevard #02-25 t/employee

3.2.3. Edit contact: contacts edit

Edits an existing person in Cow.
Format: contacts edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [t/TAG]…

  • Edits the person at the specified INDEX. The index refers to the index number shown in the displayed person list. The index must be a positive integer 1, 2, 3, …​

  • At least one of the optional fields must be provided.

  • Existing values will be updated to the input values.

  • When editing tags, the existing tags of the person will be removed i.e adding of tags is not cumulative.

  • You can specify t/ to indicate that you want to clear all existing tags.

Examples:

  • contacts edit 1 p/91234567 e/[email protected]
    Edits the phone number and email address of the 1st person to be 91234567 and [email protected] respectively.

  • contacts edit 2 n/Jane Doe t/
    Edits the name of the 2nd person to be Jane Doe and clears all existing tags.

3.2.4. Find contact: contacts find

Finds people whose names contain any of the given keywords.
Format: contacts find KEYWORD [MORE_KEYWORDS]

  • The search is case insensitive. e.g hans will match Hans

  • The order of the keywords does not matter. e.g. Hans Bo will match Bo Hans

  • Only the name is searched.

  • Only full words will be matched e.g. Han will not match Hans

  • Persons matching at least one keyword will be returned (i.e. OR search). e.g. Hans Bo will return Hans Gruber, Bo Yang

Examples:

  • contacts find John
    Returns john and John Doe

  • find Betsy Tim John
    Returns any person having names Betsy, Tim, or John

3.2.5. Delete contact: contacts delete

Deletes the specified person in Cow.
Format: contacts delete INDEX

  • Deletes the person at the specified INDEX.

  • The index refers to the index number shown in the displayed person list.

  • The index must be a positive integer 1, 2, 3, …​

Examples:

  • contacts list
    contacts delete 2
    Deletes the 2nd person in Cow

  • contacts find Jane
    contacts delete 1
    Deletes the 1st person in the list of people resulting from the contacts find command

3.2.6. Assign tasks to contact: contacts assign

Assigns a task to a specified person in Cow.
Format: contacts assign c/CONTACT_INDEX k/TASK_INDEX

  • Assigns the person at the specified CONTACT_INDEX to the task at the specified TASK_INDEX.

  • CONTACT_INDEX refers to the index number shown in the displayed person list.

  • TASK_INDEX refers to the index number shown in the displayed task list.

  • These indices must be a positive integer 1, 2, 3, …​

Examples:

  • contacts list
    tasks list
    contacts assign c/2 k/1
    Assigns the 2nd person in Cow to the 1st task in Cow

  • contacts find Alex
    tasks list
    contacts assign c/1 k/3 Assigns the 1st person in the list of people resulting from the contacts find command to the 3rd task in Cow

3.2.7. Unassign tasks from contact: contacts unassign

Unassigns a task from a specified person in Cow.
Format: contacts unassign c/CONTACT_INDEX k/TASK_INDEX

  • Unassigns an already existing assignment between the person at the specified CONTACT_INDEX to the task at the specified TASK_INDEX.

  • CONTACT_INDEX refers to the index number shown in the displayed person list.

  • TASK_INDEX refers to the index number shown in the displayed task list.

  • These indices must be a positive integer 1, 2, 3, …​

Examples:

  • contacts list
    tasks list
    contacts unassign c/2 k/1
    Unassigns the 2nd person in Cow from the 1st task in Cow

  • contacts find Alex
    tasks list
    contacts assign c/1 k/3 Unassigns the 1st person in the list of people resulting from the contacts find command from the 3rd task in Cow

3.2.8. Show tasks assigned to contact: contacts assigned

Displays all tasks assigned to the specified contact in the tasks pane. When the command is entered, you should see the list of tasks update to show only the tasks that are assigned to the specified contact.

Format: contacts assigned INDEX

  • Displays all tasks assigned to the person at the specified INDEX.

  • The index refers to the index number shown in the displayed person list.

  • The index must be a positive integer 1, 2, 3, …​

💡
 The person specified at INDEX will be highlighted, and the tasks assigned are displayed on the displayed tasks list.

Examples:

  • contacts assigned 2
    Displays all tasks assigned to the 2nd person in the current displayed person list.

  • contacts find Jane
    contacts assigned 1 Displays all tasks assigned to the 1st person in the list of people resulting from the contacts find command

3.3. Tasks

Format for entering dates is YYYYMMDD, e.g. 20183112. Format for entering times is HHMM in 24-hour time, e.g. 2359.

💡
 Most task commands have a similar format to their equivalents for contacts, except that they have different prefixes (tasks vs contacts).
ℹ️
 You are allowed to have entries with the same name.

3.3.1. View all tasks: tasks list

Shows a list of all tasks in Cow.
Format: tasks list

3.3.2. Add task: tasks add

Adds a task to Cow.
Format: tasks add n/TASK_NAME [sd/START_DATE] [st/START_TIME] ed/END_DATE et/END_TIME [t/TAG]…

  • The end date and time cannot be earlier than the start date and time.

💡
 If start date or time is not entered, the missing field(s) will default to the current date/time. Therefore, it is invalid to enter an end date and time before the current date and time.

Examples:

  • tasks add n/Math Assignment sd/20180101 st/0000 ed/20181231 et/2359 t/school t/urgent

  • tasks add n/Milk the cows ed/20181129 et/2359 t/farm

3.3.3. Edit task: tasks edit

Edits an existing task in Cow.
Format: tasks edit INDEX [n/TASK_NAME] [sd/START_DATE st/START_TIME] [ed/END_DATE et/END_TIME] [t/TAG]…

  • Edits the task at the specified INDEX. The index refers to the index number shown in the displayed task list. The index must be a positive integer 1, 2, 3, …​

  • At least one of the optional fields must be provided.

  • Existing values will be updated to the input values.

  • When editing tags, the existing tags of the person will be removed i.e adding of tags is not cumulative.

  • You can specify t/ to indicate that you want to clear all existing tags.

  • Date and time are regarded as one field, and after editing, start date and time must be before end date and time.

Examples:

  • tasks edit 1 sd/20050108 st/1235
    Edits the start date and time of the 1st task to be 8 January 2005, 12:35pm.

  • task edit 2 n/Brush the cows t/
    Edits the name of the 2nd task to be Brush the cows and clears all existing tags.

3.3.4. Search for tasks: tasks find

Find tasks based on name, start date, end date and/or tags.
When the command is entered, you should see the list of tasks update to show only the tasks that match your search request.

Format: tasks find [n/KEYWORD]…​ [sd/START_DATE] [ed/END_DATE] [t/TAG]…

  • Searching by keyword is case insensitive. e.g cows will match Cows

  • Only full words will be matched. e.g. Cow will not match Cows

  • Providing multiple keywords or tags will return tasks that match any of the keywords or tags.
    e.g. tasks find n/cow n/farm will search for tasks with either cow or farm in the name.

  • Providing multiple start dates or end dates will only use the last one for filtering.
    e.g. tasks find ed/20181130 ed/20181212 will search with end date 20181212.

  • Searching based on different criteria will return tasks that match all criteria.
    e.g. Searching on start date and end date will return tasks that match both.

Examples:

  • tasks find ed/20181130
    Displays all tasks whose end date is 30 November 2018

  • tasks find n/cows n/brush
    Displays all tasks whose name contains either cows or brush

  • tasks find t/farm t/land
    Displays all tasks that contains either the farm or land tags.

  • tasks find n/Cows t/farm
    Displays all tasks whose name contains Cows and has the farm tag.

3.3.5. Select a task: tasks select

Selects the task identified by the index number used in the displayed task list.
Format: tasks select INDEX

  • Selects the task and shows information about it in the task details pane right below the displayed task list.

  • The index refers to the index number shown in the displayed task list.

  • The index must be a positive integer 1, 2, 3, …​

Examples:

  • tasks list
    tasks select 2
    Selects the 2nd task in Cow.

  • tasks find ed/20181130
    tasks select 1
    Selects the 1st task whose end date is 30 November 2018

3.3.6. Delete task: tasks delete

Deletes all tasks corresponding to the indices provided. Format: tasks delete INDEX1 [INDEX2] [INDEX3] …​

  • Deletes tasks at the specified indices INDEX1 [INDEX2] [INDEX3]…​, and the indices need not be in order

  • There must at least be one index specified

  • The index refers to the index number shown in the displayed task list.

  • The index must be a positive integer 1, 2, 3, …​

Examples:

  • tasks delete 1
    Deletes the 1st task on the displayed task list

  • tasks delete 1 5 4
    Deletes the 1st, 4th and 5th tasks in the displayed task list

3.3.7. Delete all tasks: tasks delete all

Deletes all tasks that are shown in the displayed task list. Format: tasks delete all

💡
 If you accidentally deleted all tasks in the displayed task list, use undo to recover deleted tasks.

3.3.8. Assign person to task: tasks assign

Assigns a person to a specified task in Cow.
Format: tasks assign k/TASK_INDEX c/CONTACT_INDEX

  • Assigns the task at the specified TASK_INDEX to the person at the specified CONTACT_INDEX.

  • TASK_INDEX refers to the index number shown in the displayed task list.

  • CONTACT_INDEX refers to the index number shown in the displayed person list.

  • These indices must be a positive integer 1, 2, 3, …​

Examples:

  • contacts list
    tasks list
    tasks assign k/1 c/2
    Assigns the 1st task in Cow to the 2nd person in Cow

  • contacts list
    tasks find n/Cows
    contacts assign k/3 c/1
    Assigns the 3rd task in the list of tasks resulting from the tasks find command to the first person in Cow

3.3.9. Unassign person from tasks: tasks unassign

Unassigns a person from a specified task in Cow.
Format: tasks unassign k/TASK_INDEX c/CONTACT_INDEX

  • Unassigns an already existing assignment between the person at the specified CONTACT_INDEX to the task at the specified TASK_INDEX.

  • CONTACT_INDEX refers to the index number shown in the displayed person list.

  • TASK_INDEX refers to the index number shown in the displayed task list.

  • These indices must be a positive integer 1, 2, 3, …​

Examples:

  • contacts list
    tasks list
    tasks unassign k/1 c/2
    Unassigns the 1st task in Cow from the 2nd person in Cow

  • contacts list
    tasks find n/Cows
    tasks assign k/3 c/1
    Unassigns the 3rd task in the list of tasks resulting from the tasks find command from the first person in Cow

3.3.10. Show full details of a task: tasks assigned

Displays the contacts assigned to the task.
When the command is entered, you should see the list of contacts update to show only the contacts that are assigned to the specified task.

Format: tasks assigned INDEX

  • Displays all persons assigned to the task at the specified INDEX.

  • The index refers to the index number shown in the displayed task list.

  • The index must be a positive integer 1, 2, 3, …​

💡
 The task specified at INDEX will be selected and showed in the task details pane, and the people assigned to it are displayed on the displayed person list.

Examples:

  • tasks assigned 2
    Displays all people assigned to the 2nd task in the current displayed task list.

  • tasks find n/Cows
    tasks assigned 1 Displays all people assigned to the 1st task in the list of tasks resulting from the tasks find command

3.4. Calendar

  • Format for entering year is YYYY.

  • Format for entering month is MM.

  • Each cell in the calendar is populated with tasks that end on that day.

  • Task filters applied via the tasks find command would also apply to the tasks displayed in the calendar.

  • If there are more than 5 tasks ending on that day, the cell will be scrollable, but a scroll bar is not displayed due to space constraints.

💡
 Clicking on an entry in the calendar would display it in the task details panel.

3.4.1. View calendar for tasks due within given year and month: calendar show

Displays the specified month in the calendar panel.
Format: calendar show y/YEAR m/MONTH

ℹ️
 Entries from the end of the previous month and the start of the following month may also be displayed depending on the length and start day of the specified month.

Examples:

  • calendar show y/2018 m/12
    Displays tasks due in December 2018 in the calendar.

3.4.2. List all calendars available: calendars list [coming in v2.0]

Format: calendars list

3.4.3. Import calendar: calendars import [coming in v2.0]

Format: calendars import f/PATH_TO_FILE n/CALENDAR_NAME

3.4.4. Share calendar: calendars share [coming in v2.0]

Writes all tasks into a XML file at the specified path.

Format: calendars share f/PATH_TO_FILE

3.5. Global

3.5.1. Undo previous command undo

Restores Cow to the state before the previous undoable command was executed.
Format: undo

ℹ️

Undoable commands are commands that modify tasks, contacts and assignments thereof in Cow (commands containing add, delete, edit, assign and unassign).

Examples:

  • tasks delete 1
    tasks list
    undo (reverses the tasks delete 1 command)

  • tasks select 1
    tasks list
    undo
    The undo command fails as there are no undoable commands executed previously.

  • contacts delete 1
    contacts assign c/1 k/2
    undo (reverses the contacts assign c/1 k/2 command)
    undo (reverses the contacts delete 1 command)

3.5.2. Redo previously undone command redo

Reverses the most recent undo command.
Format: redo

Examples:

  • tasks delete 1
    tasks list
    undo (reverses the tasks delete 1 command)
    redo (reapplies the tasks delete 1 command)

  • tasks delete 1
    redo
    The redo command fails as there are no undo commands executed previously.

  • contacts delete 1
    contacts assign c/1 k/2
    undo (reverses the contacts assign c/1 k/2 command)
    undo (reverses the contacts delete 1 command)
    redo (reapplies the contacts delete 1 command) redo (reapplies the contacts assign c/1 k/2 command)

3.5.3. Clear all tasks and persons clear

Clears all tasks and persons from Cow.
Format: clear

3.5.4. Exiting the program: exit

Format: exit

3.5.5. Saving data

Data is saved to disk automatically after any command that changes the data. There is no need to save manually.