By: W13-1 Since: Sept 2018 Licence: MIT

1. Introduction

Welcome to FreeTime!

FreeTime is a desktop app that allows you to find free timeslots to meet team members for projects. More specifically, it helps you identify the times during which everyone you want to meet is free. FreeTime 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). Interested? Jump to the Section 2, “Quick Start” to get started. Enjoy!

2. Quick Start

  1. Ensure you have Java version 9 or later installed in your Computer.

  2. Download the latest FreeTime.jar here.

  3. Copy the file to the folder you want to use as the home folder for your application.

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

  5. You should see FreeTime's login screen, as follows:

    StartUpScreenFix
    Figure 1. FreeTime’s login screen, shown when you first launch FreeTime

  6. The command line is indicated by the red arrow in the figure above. Type your commands here and press Enter to execute the command.

  7. If this is your first time using FreeTime, follow the on-screen instructions to create your account.

    Creating account example:

    register u/Paul pw/12345678

    Creates an account name Paul with password 12345678

  8. After registering or logging in, you will be brought into FreeTime's main screen.

    FreeTimeMainScreenFix
    Figure 2. Window of the Main Screen of FreeTime after logging in

  9. Refer to Section 4, “Features” for details of each command.

3. Registering and Logging In

Whenever you open the application, the timetable content and commands are locked. You are required to either login with a pre-existing account, or register a new one.

FreeTime has a default user with username: test and password: test

There are five security related commands that can be entered on this command line:

  1. login

  2. register

  3. ui

  4. logout (Only when you have logged in)

  5. exit

StartUpScreenFix
Figure 3. Login Page with Red Arrow pointing to where you should enter your commands

At this page you will have to enter your credentials to log in. Only then would you be able to edit and view your own timetable, and view your friends' timetable.

Friends are other users that you have "friended", and all users start off without having any friends.

The timetable that belongs to users that are not your friends will not be available for you to see, till you add them as friends.

3.1. Logging In: login (li)

Command: login u/USERNAME pw/PASSWORD

Examples:

  • login u/test pw/test
    Logins with Username: test and Password: test

  • login u/tim pw/tam
    Logins with Username: tim and Password: tam

You are required to to enter a password that contains more or equal to 8 characters. To ensure that your account is well-protected, do use a password that is not common.

3.2. Registering: register (re)

Command: register u/USERNAME pw/PASSWORD e/[EMAIL] p/[MOBILEPHONE] a/[ADDRESS]

Examples:

  • register u/tim pw/tam e/tim@tam.com p/88888888 a/Tammy Road

Only the Username and Password fields are necessary, the others are optional and you are not required to enter them.

3.3. Showing the UI Interface: (ui)

Command: ui

Entering the command ui will cause the Login Window to appear as seen in figure 4.

LoginUI
Figure 4. Login UI

Clicking on the Register button changes your view to the Registration Window seen in figure 5.

RegisterUI
Figure 5. Registration UI

4. Features

This section contains all of the features that are currently present in FreeTime. Feel free to click any one of the links to quickly jump to the feature!

Table 1. Overview of all the features in FreeTime
Feature Function

help (h)

Opens the help window

edit (ed)

Edits your information in the database

find (f)

Filters the database based on the keywords specified

group (g)

Filters the database based on the group tags specified

listall (l)

Lists all the users in the database

friend (af)

Adds a user to your friend list

unfriend (uf)

Removes a friend from your friend list

select (s)

Selects a user in your friends list and shows their timetable

add (a)

Adds a timeslot to your timetable

delete (d)

Removes a timeslot from your timetable

clear (c)

Clears all timeslots from your timetable

free (fr)

Highlights timeslots where you and everyone specified is free

import (im)

Imports a timetable for the current user from a specified (.ics) file

export (ex)

Exports the currently-displayed timetable to the specified (.ics) file

undo (u)

Restores the address book to the state before the previous undoable command was executed.

redo (r)

Reverses the most recent undo command

history (hi)

Lists all the commands that you have entered in reverse chronological order

logout (lo)

Logs out of FreeTime and brings you back to the login screen

exit (x)

Closes FreeTime

Command Format

  • Each command has an alias (given in round brackets after the command word) that can be used to replace the full command word. e.g. find John is equivaluent to f John.

  • Words in UPPER_CASE are the parameters to be supplied by the user e.g. in edit p/PHONE, PHONE is a parameter which can be used as edit p/12345678.

  • Items in square brackets are optional e.g [p/PHONE_NUMBER][g/GROUP] can be used as p/12345678 g/CS2101 or as g/CS2101.

  • Items with …​ after them can be used multiple times including zero times e.g. [g/GROUP]…​ can be used as   (i.e. 0 times), g/CS2101, g/CS2113T g/W13-1 etc.

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

4.1. Viewing help : help (h)

Displays the User Guide from within the app.

Format: help

Jump back to FreeTime's feature list

4.2. Editing a person : edit (ed)

Edits your information in the database.

Format: edit [p/PHONE] [e/EMAIL] [a/ADDRESS] [g/GROUP]…​

  • Existing values will be updated to the input values.

  • When editing groups, your existing groups will be removed. i.e adding groups is not cumulative.

  • You can remove all your groups by typing g/ without specifying any groups after it.

  • Groups should be alphanumeric (contains letters and numbers), and can also contain hyphens "-" and underscores "_"

Jump back to FreeTime's feature list

4.3. Locating persons by name : find (f)

Finds persons whose names contain any of the given keywords.

Format: 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:

  • find John
    Returns john and John Doe

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

Jump back to FreeTime's feature list

4.4. Locating persons by group : group (g)

Find persons whose groups match the specified groups.

Format: group GROUPNAME [MORE_GROUPNAMES]

  • By default, FreeTime shows all the users that are using the application, on both the Friends and Others panel.

  • The search is case sensitive. e.g CS2101 will not match cs2101

  • The order of the groups do not matter. e.g. CS2101 CS2113T will match CS2113T CS2101

  • Persons matching at least one group will be returned (i.e. OR search). e.g. CS2113T CS2101 will return persons with in either CS2101 or CS2113T groups

Example:

  • group CS2101
    Filters both the others list and the friends list to show only users with the group "CS2101".

  • group CS2101 CS2113T
    Filters both the others list and the friends list to show only users with both group "CS2101" and "CS2113T".

Use the command listall to revert the panels back to its original state.

Jump back to FreeTime's feature list

4.5. Listing all persons : listall (l)

Shows a list of all persons in FreeTime.

Format: listall

After filtering your results by executing commands such as group or find, executing listall will revert the list back to it’s initial state

Jump back to FreeTime's feature list

4.6. Adding a person to your friend list : friend (af)

Adds a person from the others list to your friend list.

Format: friend INDEX

  • Personal information of the user will be obscured until you have befriended them.

  • Most commands in this application (like free and select) can only be executed only after adding someone to your friend list.

  • You can only befriend someone who is in the others list.

  • The indices must be positive integers 1, 2, 3, …​ and have to match someone on the others list

Examples:

  • friend 1
    Adds the first user in the others list to your list of friends.

    1. Before executing the command, your window might look like the following, without friends:

      BeforeAddingFriendsPS
      Figure 6. Before adding friend to your friend list.

    2. After executing friend 6, there will be a success message and the first person should be added to the friend’s list, as follows:

      AfterAddingFriendsPS
      Figure 7. After adding friend to your friend list.

    3. More information about the user is now shown and commands such as free and select can now be used.

Jump back to FreeTime's feature list

4.7. Removing a person from your friend list : unfriend (uf)

Removes a person from your friend list.

Format: unfriend INDEX

  • You can only unfriend someone who is in your friends list.

  • The indices must be positive integers 1, 2, 3, …​ and have to match someone on the friends list

Example:

  • unfriend 1
    Removes the first user from the friends list.

    1. Before executing the command, look for the index of the person you would like to remove from your list:

      BeforeRemovingFriendsPS
      Figure 8. Before removing friend from friend list.

    2. After executing unfriend 1, there will be a success message and the first person should be removed from the friend’s list, as follows:

      AfterRemovingFriendsPS
      Figure 9. After adding friend to your friend list.

    3. More information about the user is now shown and commands such as free can now be used.

Jump back to FreeTime's feature list

4.8. Selecting a person : select (s)

Selects your friend with the specified index, showing you their timetable.

Format: select INDEX

  • The index refers to the index number shown in your friend list.

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

  • You cannot select someone who is not your friend yet. Try using the friend command first!

  • You can select yourself by using the command select me

Examples:

  • select me
    Selects yourself.

  • select 2
    Selects the 2nd person listed in your friend list.

  • find Betsy
    select 1
    Selects the 1st person in the results of the find command.

Jump back to FreeTime's feature list

4.9. Add a timeslot to your timetable: add (a)

Adds a timeslot to your timetable.

Format: add Monday 10:00-12:30

  • FreeTime uses the 24-hour clock, so 01:00 means 1 am, not 1 pm!

  • Shortforms for the day of the week are fine too. e.g. you can type Mon instead of Monday.

  • If you type a single number, like 10 for either the start or end time, FreeTime will assume that you mean 10:00.

  • You cannot add a timeslot that clashes with your current timetable.

Examples:

  • add Monday 10:00-12:30
    Adds the timeslot from 10:00 to 12:30 on Monday to your timetable.

  • add Fri 13:30-14:00
    Adds the timeslot from 13:30 to 14:00 on Friday to your timetable.

  • add Wed 17-18
    Adds the timeslot from 17:00 to 18:00 on Wednesday to your timetable.

After adding a timeslot, you should see the following:

AddTimeSuccess
Figure 10. Timeslot added to your timetable

Jump back to FreeTime's feature list

4.10. Delete a timeslot from your timetable: delete (d)

Deletes a timeslot from your timetable.

Format: delete Monday 10:00-12:30

  • FreeTime uses the 24-hour clock, so 01:00 means 1 am, not 1 pm!

  • Shortforms for the day of the week are fine too. e.g. you can type Mon instead of Monday.

  • If you type a single number, like 10 for either the start or end time, FreeTime will assume that you mean 10:00.

  • You cannot delete a timeslot that is not already in your timetable.

Examples:

  • delete Monday 10:00-12:30
    Deletes the timeslot from 10:00 to 12:00 on Monday from your timetable.

  • delete Fri 13:30-14:00
    Deletes the timeslot from 13:30 to 14:00 on Friday from your timetable.

  • delete Wed 17-18
    Deletes the timeslot from 17:00 to 18:00 on Wednesday from your timetable.

Jump back to FreeTime's feature list

4.11. Clears your timetable : clear (c)

Clears all timeslots from your timetable.

Format: clear

Jump back to FreeTime's feature list

4.12. Show free slots among selected people: free (fr)

Highlights timeslots where you and everyone specified is free.

Format: free INDEX…​

  • You can specify more than one friend.

  • The indices refer to the index number shown in your friend list.

  • The indices must be positive integers 1, 2, 3, …​

Examples:

  • free 1 2
    Highlights timeslots where you, friend 1, and friend 2, are all free to meet up.

After executing the command, you should see the following:

FreeTimeSuccess
Figure 11. Timeslots highlighted in green are available while timeslots highlighted in red are unavailable.

Jump back to FreeTime's feature list

4.13. Import Timetable : import (im)

Use this command to import a timetable for the current user from a specified file.
See the example below for a quick start!

Format: import FILE_NAME

  • Command parameters:

    • FILE_NAME refers to the name of the file that you want to import.

      • Do not include the .ics file extension when typing the command.

      • In other words, type: import nusmods_calendar instead of import nusmods_calendar.ics

  • Compatibility:

    • Only supports .ics files exported from NUSMODS.

  • Location of the import file:

    • The file will be imported from the folder import_export, which is located in the same folder as the FreeTime.jar file.

      • Please see the image below:

UG import directory
Figure 12. Location to put your import files.

Example:

  • import nusmods_calendar
    Imports the timetable from .\import_export\nusmods_calendar.ics
    (where . represents the folder that the application is in.)

    1. Download your file from NUDMODS website:

      UG import step 1
      Figure 13. Download your file from NUDMODS website.

    2. Copy your desired .ics file to the import_export folder:

      UG import step 2
      Figure 14. Copy your file to the correct folder.

    3. Go back to FreeTime, and type in the command import nusmods_calendar :

      UG import step 3
      Figure 15. Type this, then press enter!

    4. If the import was successful, FreeTime should look similar to this :

      UG import step 4
      Figure 16. Import Success! :)

      Jump back to FreeTime's feature list

4.14. Export Timetable : export (ex)

Use this command to export the currently-displayed timetable as an .ics file. See the example below for a quick start!

Format: export FILE_NAME

  • See the example below for a quick start!

  • Command parameters:

    • FILE_NAME refers to the name of the file that you want to export.

      • Do not include the .ics file extension when typing the command.

      • In other words, type: export my_timetable instead of export my_timetable.ics

  • Compatibility:

    • Can be imported back into FreeTime

  • Location of the exported file:

    • The file will be exported to the folder import_export, which is located in the same folder as the FreeTime.jar file.

      • Please see the image below:

UG export directory
Figure 17. Location of your exported files.

Example:

  • export my_timetable
    Exports the displayed timetable to .\import_export\my_timetable.ics
    (where . represents the folder that the application is in.)

    1. Ensure that the timetable you want to export is being shown:

      1. type select me to display your own timetable.

      2. type select INDEX to display one of your friend’s timetable.

        UG export step 1
        Figure 18. Select the desired timetable.

    2. Type the command export my_timetable:

      UG export step 2
      Figure 19. Type the command.

    3. If the export was successful, Your timetable should be waiting for you in the folder :

      UG export step 3
      Figure 20. Exported file is in the import_export folder

Jump back to FreeTime's feature list

4.15. Undoing previous command : undo (u)

Restores FreeTime to the state before the previous undoable command was executed.

Format: undo

Undoable commands: edit, add, delete, clear, import.

Examples:

  • import my_file
    undo (reverses the import my_file command)

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

  • import my_file
    clear
    undo (reverses the clear command)
    undo (reverses the import my_file command)

Jump back to FreeTime's feature list

4.16. Redoing the previously undone command : redo (r)

Reverses the most recent undo command.

Format: redo

Examples:

  • delete mon 8-10
    undo (reverses the delete mon 8-10 command)
    redo (reapplies the delete mon 8-10 command)

  • delete mon 8-10
    redo
    The redo command fails as there are no undo commands executed previously.

  • delete mon 8-10
    clear
    undo (reverses the clear command)
    undo (reverses the delete mon 8-10 command)
    redo (reapplies the delete mon 8-10 command)
    redo (reapplies the clear command)

Jump back to FreeTime's feature list

4.17. Listing entered commands : history (hi)

Lists all the commands that you have entered in reverse chronological order.

Format: history

Pressing the ↑ and ↓ arrows will display the previous and next input respectively in the command box.

Jump back to FreeTime's feature list

4.18. Logging Out : logout (lo)

Command: logout

To use this command, you would have to be logged in first. Typing logout as seen in the figure below return you back to the login page.

Logout
Figure 21. Logout Command entered into command line

Jump back to FreeTime's feature list

4.19. Exiting the program : exit (x)

Closes the FreeTime application.

Format: exit

This command closes the application without logging you out. It is recommended to logout before doing this, or the changes to your timetable might be lost.

Jump back to FreeTime's feature list

4.20. Saving the data

Application data is saved in the hard disk automatically, every time the data is changed.
There is no need to save manually.

5. FAQ

Q: How do I transfer my data to another Computer?
A: Install the app in the other computer and overwrite the empty data file it creates with the file that contains the data of your previous FreeTime folder.