By: W11-1 Since: Feb 2019 Licence: MIT

1. Introduction

TopDeck is a desktop app for anyone who relies on flash cards to memorise things.

TopDeck helps you digitise your flash cards and keeps them organised. You can easily review your cards and TopDeck will track your performance. Improve your memory without the hassle of managing a physical pile of cards!

TopDeck has a Command Line Interface (CLI), which means you interact with it by typing commands. TopDeck can be operated entirely using the keyboard!

If this sounds like the tool you have been looking for, jump to Section 2, “Quick start” to get started. Enjoy!

2. Quick start

To get started with TopDeck:

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

  2. Download the latest topdeck.jar here.

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

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

    Ui
    Figure 1. TopDeck’s initial GUI

  5. Type the command in the command box and press Enter to execute it.
    e.g. typing help and pressing Enter will open the help window.

Once you have set up TopDeck, you can try these commands:

  • add Parseltongue : creates a new deck named "Parseltongue"

  • delete 3 : deletes the third deck in the list

  • exit : exits the app

You may refer to Section 4, “Commands” for details of each command.

3. User interface

TopDeck’s interface is very simple. It consists of four main areas - the Menu Bar, the Command Box, the Results Display, and the Content Panel.

ui annotate
Figure 2. Main areas in the user interface

Here are the uses of each part of the interface:

  • Menu Bar: Provides access to general commands such as exit and help with dropdowns.

  • Command Box: This is where you input commands to interact with the application.

  • Results Display: This area shows the outcome of your commands.

  • Content Panel: This is the main display area and changes depending on what you are doing.

TopDeck’s functionality is separated into three distinct views - decks view, cards view and study view. The interface shown in the Content Panel and the commands available change depending on the view. By default, TopDeck starts in decks view.

Navigation
Figure 3. Navigating the views in TopDeck

The figure above provides a brief overview of the different views and shows how you may navigate between them. In general, the commands open, study and back are used to navigate to cards view, study view and decks view respectively. For more information about these commands, go to Section 4, “Commands”.

The following sections will describe each view in more detail.

3.1. Decks view

deck
Figure 4. Decks view

Decks view displays a list of the decks in your collection. The figure to the right shows a typical TopDeck session in decks view.

In decks view, you can:

  • Create a new deck.

  • Edit, delete, or search for an existing deck.

  • Open a deck to view its contents. TopDeck will open the deck in cards view.

  • Pick a deck to study. TopDeck will use the deck in study view.

  • Export a deck in your collection or import a deck from your computer to TopDeck.

You may find the corresponding commands for the features in decks view here.

3.2. Cards view

cards
Figure 5. Cards view

Cards view displays the cards in a particular deck. The figure to the right shows a typical TopDeck session in cards view.

In cards view, you can:

  • Create a new card and add it to the deck.

  • Edit, delete, or search for an existing card in the deck.

  • View your past study performance for specific cards.

You may find the corresponding commands for the features in cards view here.

3.3. Study view

study
Figure 6. Study view

In study view, TopDeck helps you to study a particular deck. The figure to the right shows a typical TopDeck session in study view.

The cards from a particular deck will be shown one at a time. TopDeck will first show a question. You may then reveal the answer and verify if it matches your answer. Finally, you may rate how well you think you performed for that card before moving on to the next card. TopDeck automates the bookkeeping for you.

You may find a more precise decription of the commands used in cards view here.

4. Commands

Command Format

  • Words in UPPER_CASE are the parameters to be supplied by the user.
    Example: In add DECK_NAME, DECK_NAME is a parameter which can be used as add Spanish.

  • Items in square brackets are optional.
    Example: q/QUESTION a/ANSWER [t/TAG] can be used as q/China a/Beijing t/Asia or as q/China a/Beijing.

  • Items with …​ after them can be used any number of times including zero.
    Example: [t/TAG]…​ can be used as   (i.e. 0 times), t/Asia, t/trivia t/history etc.

  • Parameters can be in any order.
    Example: If the command specifies q/QUESTION a/ANSWER, a/ANSWER q/QUESTION is also acceptable.

  • If you provide multiple parameters for fields that do not support multiple arguments, only the last argument will be accepted. I.e. If you entered add n/nameOne n/nameTwo, the new deck will have the name "nameTwo".

4.1. Decks view

In this view you can create, edit and find decks. This is the default view when TopDeck is first launched.

These are commands only available in deck view.

4.1.1. Creating a deck: add

Format: add n/DECK_NAME

Outcome: Creates a new deck called DECK_NAME.

Example: add n/History

Here is what you type in.

add

The deck should appear at the bottom of the list.

Before:

add deck 1

After:

add deck 2

4.1.2. Deleting a deck: delete

Format: delete INDEX

Outcome: Deletes the deck at INDEX.

Example: delete 2

The index refers to the index number shown in the displayed deck list. The index must be a positive integer 1, 2, 3…​

Before:

delete deck 1

After:

delete deck 2

4.1.3. Editing the name of a deck: edit

Format: edit INDEX n/NEW_DECK_NAME

Outcome: Changes the name of the deck at INDEX to NEW_DECK_NAME.

Example: edit 2 n/Addition

Before:

edit deck 1(1)

After:

edit deck 2(2)

4.1.4. Finding a deck by name: find

Format: find KEYWORD

Outcome: Lists all decks containing KEYWORD in its name.

Example: find sci

Before:

find deck 1(1)

After:

find deck 2(2)

4.1.5. Listing all decks: list

Format: list

Outcome: Displays a list of all decks.

list deck 1(1)
list deck 2(2)

Format: open INDEX

Outcome: Opens the deck at INDEX

Example: open 1

open deck(1)

4.1.7. Studying a deck: study

Format: study INDEX

Outcome: Enters study view with the deck at INDEX.

Example: study 1

study deck(1)

4.1.8. Import a deck: import

To import a deck from the json file at the specified FILEPATH.
Format: import FILEPATH

  • You must include the filename of the target file in FILEPATH.

  • This operation is only available in Decks view.

  • The default base directory is the directory that the TopDeck.jar file is in.

Example: Say you want to import a deck called "Economics" and you have the Economics.json file in the same folder as TopDeck.jar.

import deck 1

  • Simply enter import Economics and TopDeck will import the deck "Economics".

Before:

import deck 2(2)

After:

import deck 3(3)

4.1.9. Export a deck: export

To create a json file of the deck at INDEX.
Format: export INDEX

  • INDEX must be a positive integer from 1 onwards and is based on the currently displayed list.

  • This operation is only available in Decks view.

  • The json file will be created in the same directory as the TopDeck.jar file.

Example:

  • 1. First, display all the decks in TopDeck using list.

list deck 2(2)

  • 2. Say you want to export "History" (the 3rd deck), simply enter the command: export 3. You should see the following message:

export deck 1

"Economics.json" will be created in the same directory as the TopDeck.jar file.

export deck 2

4.1.10. Selecting a deck: select

Currently select does not do much. However, we will be adding more functionality for select in v2.0. Refer to Section 8, “Upcoming Features” for more details.

4.2. Cards view

These commands are only available in cards view. In this section, the active deck is the deck used in the open command.

The Footer Bar will continue to track the number of decks in the app.

4.2.1. Selecting a card in the active deck: select

Format: select INDEX

Outcome: Selects the card in the deck with index at INDEX

Example: select 1

4.2.2. Adding a card to the active deck: add

Format: add q/QUESTION a/ANSWER [t/TAG]

Outcome: Creates a new card with question and answers and adds it to the current deck.

Example: add q/Hello a/World t/TopDeckSample

Below is an example of what the user should see upon the execution of the command:

Before:

add card 1

After:

add card 2

4.2.3. Deleting a card in the active deck: delete

Format: delete INDEX

Outcome: Deletes the card at INDEX

Example: delete 2

4.2.4. Editing a card in the active deck: edit

Format: edit INDEX q/QUESTION a/ANSWER [t/TAG]

Outcome: Edits the text of the card at INDEX.

Example: edit 1 q/Edit Hello a/World t/Edited

Auto-Complete: Instead of typing the whole command, TopDeck also provides an auto-complete feature for the edit command. Users need only type edit INDEX and TopDeck will fill up the commandline for the user to edit accordingly.

Edit will only edit the question, answer and tags of a card. It will not affect the statistics of a card.

Below is a walk-through of the edit command:

Suppose the user adds a new card with a typo:

edit card 1

The user can then retrieve the full detail of the card by simply typing edit 2 and pressing enter. The following would appear

edit card 2

The user can then edit and correct the mistake made.

edit card 3

This would be the end result:

edit card 4

4.2.5. Finding a card in the active deck by name: find

Format: find KEYWORD [KEYWORD]…​

Search for phrases: TopDeck provides the user the ability to search for specific question by searching for a whole phrase instead of only individual words. This is done by putting " around KEYWORD. The find command searches all KEYWORD between 2 " and so there should not be any " character in KEYWORD. Searching using phrases only searches the question.

Outcome: Lists all cards within the current deck containing KEYWORD in its text.

find will only search for full-matching words. For e.g. Animals will not be found if animal is used to search for it.
The entire phrase inside " will be matched word for word. For example, find "Is there a question" will display the questions with the entire phrase Is there a question and the question Is there a question? will not be matched due to the extra ?.

Example:

  • find Singapore

Below is the result of executing this command:

find card 1

  • find "When was Singapore founded?"

Below is the result of executing this command:

find card 2

4.2.6. Clearing all cards in the active deck: clear

Format: clear

Outcome: Clears all of the cards in the deck.

4.2.7. Listing all cards in the active deck: list

Format: list

Outcome: Displays a list of all cards in the deck.

4.2.8. Studying the active deck: study

Format: study

Outcome: Enters study view with the current deck.

4.2.9. Returning to decks view: back

Format: back

Outcome: Returns to decks view.

4.2.10. Adding a picture to a card [Coming in V2.0]

Format: addImg INDEX IMAGEPATH

Outcome: Adds the image as a question to the card at INDEX

4.3. Study View

Study view can be accessed using any of these commands:

  • study INDEX from decks view

  • study from cards view

In order to facilitate your study session, Study view presents Flash Cards in two phases, namely Question Phase and Answer Phase.

4.3.1. Question Phase

Study view starts off in Question Phase, which displays the question in this user interface:

question
Figure 7. Study view’s Question Phase

As seen above, the question to be answered is displayed in a dark blue flash card.

Currently, questions are chosen this way: TopDeck shuffles the deck and displays cards one at a time until the entire deck has been viewed. Topdeck repeats this endlessly until you choose to end your study session.

You may attempt the question by typing your answer into the Command Box, which now doubles as an Answer Box. Once you’re ready to see the answer, hit Enter. Your attempt will be recorded and TopDeck will enter Answer Phase.

4.3.2. Answer Phase

During this phase, you will see the answer to the earlier question in the following user interface:

answer
Figure 8. Study view’s Answer Phase

As seen from the figure, the correct answer is displayed on a white flash card. Your attempt is shown on top next to the card for your own comparison.

Additionally, a prompt asks you to rate the difficulty of that flash card. You should input your rating into the Command Box which now doubles as a Rating Box.

Once you’ve typed in your rating, hit Enter. Your rating will be recorded and this value will contribute to average difficulty statistic seen in cards view. Immediately after that, TopDeck will reenter Question Phase.

Your rating can be any integer between 1-5. You may type it together with other words, e.g. "1 easy" but the program will only look at the first word/integer.

During both phases, the following commands are available to end your study session:

4.3.3. Returning to decks view: back

Format: back

Outcome: Returns to decks view.

4.3.4. Opening the deck in cards view: open

Format: open

Outcome: Opens the deck in cards view.

The command can include other words e.g. "open sesame", but as long as your command’s first word is a command word, running the commands will be prioritised.

4.4. Global commands

These commands are available in all views.

4.4.1. Listing entered commands : history

Format: history

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

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

4.4.2. viewing help : help

Format: help

Outcome: Displays information regarding commands

4.4.3. Exiting the program : exit

Format: exit

Outcome: Exits the program

4.4.4. Clearing all entries : clear

Format: clear

Outcome: Clears all entries in TopDeck

Clearing TopDeck is disabled in study view.

4.4.5. Undoing a command : undo

Format: undo

Outcome: Restores TopDeck to the state before the previous change.

Examples:

  • In decks view
    delete 1
    undo (undos delete 1)

  • In cards view
    delete 1
    add q/Russia a/Moscow
    undo (undos add)
    undo (undos delete)

Undoing is disabled in study view.

4.4.6. Redoing a command : redo

Format: redo

Outcome: Restores the TopDeck to the state before an undo.

Examples:

  • delete 1
    undo (undos delete 1)
    redo (redos delete 1)

  • delete 1
    redo
    The redo command fails as there is no undone state to restore.

  • In cards view
    delete 1
    add q/Panama a/Panama
    undo (undos add)
    undo (undos delete)
    redo (redos delete)
    redo (redos add)

Redoing is disabled in study view.

4.4.7. Saving your data

TopDeck data is saved in the hard disk automatically after any command that changes the data.
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 TopDeck folder.

6. Glossary

Card: Flash cards in TopDeck are called cards. Each card contains a question-answer pair. When studying, TopDeck will show the question, and the answer will be revealed when prompted by the user.

Deck: A deck is a collection of cards that are studied together.

7. Command Summary

A convenient cheat sheet of commands

7.1. Decks view

add n/NAME

Adds a new deck.

delete INDEX

Deletes the deck at INDEX.

edit INDEX n/NAME

Edits the name of the deck at INDEX.

find NAME

Finds a deck by name.

list

Displays a list of all available decks.

open INDEX

Navigates into the deck at INDEX.
Use back to navigate out of the deck.

study INDEX

Studying the deck at INDEX.

import FILEPATH

Imports a deck from the json file at the specified FILEPATH.

export INDEX

Exports the deck at the specified INDEX. (Default location is the same folder as TopDeck)

select INDEX

Selects the deck at the specified INDEX. (Does not do much now, more functionality will be added in v2.0)

7.2. Cards view

add q/QUESTION a/ANSWER

Adds a new card in the current deck.

delete INDEX

Deletes the card at INDEX.

edit INDEX [q/QUESTION]-[a/ANSWER]

Edits the details of the card at INDEX.
At least one parameter must be present.

find NAME

Finding a card in the active deck by name.

list

Displays a list of all available cards.

study

Studying the active deck.

7.3. Study view

back

Returning to deck view after studying.

open

Opens the deck in cards view.

7.4. Global Commands

clear

Clear all decks and cards. (Disabled in study view)

exit

Exits the program.

help

Lists all available commands and their respective formats.

history

List all entered commands in reverse chronological order.

redo

Redo previously undone command. (Disabled in study view)

undo

Undo previous command. (Disabled in study view)

7.5. Switching views

back

Cards/study view to decks view.

open

Study view to cards view.

open DECK_INDEX

Decks view to cards view

study

Cards view to study view.

study DECK_INDEX

Decks view to study view.

8. Upcoming Features

Selecting a deck in Decks view using the select command will produce a report of your performance for that deck.