Skip to content

🧮 Mental Calculation Game Mode (Developer Docs)

The MentalCalculationFragment implements the Mental Arithmetic Game Mode in zMantra.
It challenges learners to solve arithmetic problems by listening to math expressions and entering answers.
This mode emphasizes auditory math comprehension, step-by-step reading, and time-limited problem solving.

📂 Location

com.zendalona.zmantra.presentation.features.game.mentalcalculation.MentalCalculationFragment

🔑 Core Responsibilities

  1. Display & Read Arithmetic Problems
  2. Math expressions are broken into tokens (e.g., "12 ÷ 3 + 5" → "12", "÷", "3", "+", "5").
  3. Tokens are revealed sequentially with delays, supporting cognitive load management.

  4. Uses TTSHelper and AccessibilityUtils for TalkBack users.

  5. User Answer Input

  6. Learner enters numeric answers into EditText (answerEt).

  7. Submission via button or keyboard Enter/Done action.

  8. Validation & Feedback

  9. Compares learner’s answer to correctAnswer.
  10. Provides toast feedback for empty or invalid inputs.

  11. Calls handleAnswerSubmission() from BaseGameFragment to standardize scoring and flow.

  12. Accessibility

  13. Uses TalkBack announcements for token-by-token reading.
  14. Prevents unwanted auto-keyboard popup (users manually open).

  15. Keeps clear separation of Read Question vs Answer Input focus.

  16. Game Flow Control

  17. Cycles through GameQuestion list sequentially.
  18. Ends session when all questions are attempted (endGame()).

⚙️ Key Fields

Variable Type Purpose
binding FragmentGameMentalCalculationBinding? View binding for layout.
handler Handler(Looper.getMainLooper()) Manages delayed token reveals.
questions List<GameQuestion> All math problems for this session.
currentIndex Int Current question index.
correctAnswer Int Expected numeric result of current problem.
startTime Long Timestamp when problem begins (for timing).
revealTokens List<String> Tokens of current math expression.
revealIndex Int Position of next token to reveal.
isRevealing Boolean Prevents overlapping token reveal calls.

🔄 Lifecycle

  1. onCreateView()
  2. Inflates layout.
  3. Sets listeners for:
    • Read Question button → onReadQuestionClicked().
    • Submit Answer button → checkAnswer().
    • IME Action Done/Enter key → checkAnswer().

  4. Handles focus to prevent keyboard auto-popup when toggling between Read/Answer.

  5. onQuestionsLoaded()

  6. Loads provided GameQuestions.
  7. If none provided → fallback default ("1 + 2").

  8. Calls loadNextQuestion().

  9. onReadQuestionClicked()

  10. Splits expression into tokens (numbers and operators).
  11. Begins sequential reveal (showToken() every 1s).

  12. Disables button while reading to avoid re-entry.

  13. revealNextToken() / showToken()

  14. Displays token visually and via TalkBack (announceForAccessibility).

  15. Replaces / with ÷ for better readability.

  16. loadNextQuestion()

  17. Resets UI and attempts.
  18. Reads expression tokens aloud if TalkBack is active.

  19. Re-enables input after reveal delay.

  20. checkAnswer()

  21. Validates input from answerEt.
  22. If empty → prompt user with toast.
  23. If non-numeric → error toast.
  24. Else → compare against correctAnswer.
  25. On correct: optional bell sound effect if celebration == true.
  26. On incorrect: clear input and refocus.

  27. On show correct: skip to next.

  28. onPause()

  29. Stops token reveals and TTS.

  30. onDestroyView()

  31. Clears binding to avoid leaks.

🎧 Accessibility

  • Token-by-token spoken announcements for math expressions.
  • Prevents keyboard interference when toggling focus.
  • Custom TTS formatting via TTSHelper.formatMathText().
  • Explicit TalkBack instructions: "Solve 12 ÷ 3 + 5".

🧪 Testing Notes

  • Verify token reveal timing (1 second per token).
  • Confirm Read Question button is disabled during reveal.
  • Test answer validation:
  • Empty → "Enter answer".
  • Wrong input → "Wrong answer".
  • Correct → proceeds to next with optional bell sound.
  • Ensure time tracking works: elapsed vs timeLimit.
  • Check TalkBack flow:
  • Announces "Solve expression" at start.
  • Announces each token sequentially.