Projects/Edu/Parley/Practice/Mode Creation Guide

Guide to Making New Practice Modes

Starting Out

The first step to making a new practice mode is deciding what it will test. For this guide, we will be tracing the creation of the Synonym practice mode.

Synonym practice gives the user a list of choices and asks her to identify which is a synonym of the selected word. The choices are in the same language as the prompt word, and there is a set list of them. We provide a set list because our program has no way to decide if an arbitrary word is a synonym of another arbitrary word.

Parley already keeps a list of synonyms in each practice entry and we can just compare a selected answer against that list, so we have no need of special code.

From this, we can identify the following traits:

• Monolingual/bilingual: Monolingual
• Format: Multiple choice
• Special code: No.

Themeing

The first step is deciding if your new mode fits any of the preexisting templates. A mode fits a template if the template's mode of display and user input fit with the needs of the mode.

Out of the available mode templates (below), multiple choice clearly fits synonym practice best, as it allows a closed set of answers, displays the possible answers, and provides the basic question prompt.

If your mode is radically different, and does not fit into any of the templates, it will require a special theme entry and more extra code. Avoid this when possible to keep any current themes valid.

It is suggested that you read the theme requirements page to get an idea for what is involved in a theme.

Mode Templates

Multiple choice

This template works best for practice modes that have a closed set of possible answers or for those which you want the user to know the available options.

Examples: Generic multiple choice mode, synonym mode

Written

This template works best if the possible set of answers is open or you don't want to supply the user with choices. This is a very flexible mode.

Examples: Generic written mode, paraphrase, example

Mixed letters

This mode is like written, but provides an additional hint (the mixed letters portion).

Example: mixed letters mode.

Flashcards

This mode emulates the classic flashcards approach. This mode does no correction and counts on the honesty of the user.

Example: Flash card mode

Comparison

This mode is designed for comparison only. If you want to use a template of this style, use the conjugation template instead.

Example: Comparison mode

Conjugation

This mode is best if you want up to four written questions (that are hopefully somehow related) asked and corrected at the same time. These modes are more complicated to add, so I suggest avoiding them if possible.

Example: Conjugation mode

Easy Steps to Victory

• Add an entry in the practice "TestType" enum in parley/src/settings/parley.kcfg for your mode. Also add any other special mode settings you may need in this file. Follow the existing nomenclature.
  • Here we would add SynonymTest.

• Search throughout the source for "switch (Prefs::testType())" and add your mode to the switch statements. If the switch is not mentioned in this guide, follow the comments or common sense.
  • Since synonym mode is very similar to multiple choice and uses the multiple choice template, we usually add it near MultipleChoiceTest.

• In PracticeEntryManager::testCategory(), add your mode above whatever template mode you have chosen.
  • We would add synonym mode to MultipleChoiceTemplate.

• In ParleyPracticeMainWindow::setupActiveArea(), pass a string with your mode name in it first and the name of the template mode second. This allows theme designers to make a specific active area for your mode, but will fall back to the template mode if they don't.
  • We would use "synonym" and "multiple_choice" for the first and second arguments, respectively.

• Add your mode to the theme requirements page so theme designers know it exists and what it requires.

• Add your mode to the options dialog in parley/src/config-practice/. This may require making a .ui file if your mode has special settings.
  • Synonym requires no special options, so it doesn't need a .ui file.

• Success!