alto.ui.exercise_view
The exercise screen: a question, its answer buttons, the score, and a pane of settings that slides in from the right.
One ExerciseView works for every exercise. It asks the exercise (or, with a profile, the learner) for the next
Question, shows it as a staff, a keyboard or text, offers the answer buttons, and records each answer.
Examples
>>> from alto.exercises.library import NoteNames
>>> view = ExerciseView(NoteNames(), rng=random.Random(1))
>>> # noinspection PyUnresolvedReferences
>>> view.question.answer in [button.text() for button in view.buttons]
True
choice_keys
def choice_keys(choices: list[str]) -> list[str]
Choose a key for each answer button, so that every answer can be given from the keyboard.
Nine answers or fewer take the digits 1 to 9. More than that, as on the piano keyboard, take the notes’ own names: the letter for a natural, Shift and the letter for a sharp, Ctrl and the letter for a flat. A minor key, such as F♯m, is typed the same way as the major key of its name. Any other long list takes 1 to 9 and then 0, and the rest can be reached with Tab. Scale-degree banks use the degree digit, with Shift for a sharp, Ctrl for a flat, and Alt added for double alterations.
Parameters
choices(list of str): The answers, in the order of their buttons.
Returns
- list of str: A key for each answer, such as “3” or “Shift+C”; “” for an answer that has none.
Examples
>>> choice_keys(["major", "minor", "diminished"])
['1', '2', '3']
>>> choice_keys(list("CDEFGAB") + ["C♯", "B♭"] + ["F♯"])
['C', 'D', 'E', 'F', 'G', 'A', 'B', 'Shift+C', 'Ctrl+B', 'Shift+F']
>>> choice_keys([str(n) for n in range(12)])[8:]
['9', '0', '', '']
second_row_keys
def second_row_keys(
first: list[str],
*,
labels: list[str],
) -> list[str]
Choose a key for each button of the second row of a two-part answer, such as the octave or the inversion.
They must not be keys that the first row has. When the first row uses the digits the second row takes the home row, A S D F and so on; when the first row uses letters (the notes’ names) it takes the digits, and an octave that is a single digit takes that digit.
Parameters
first(list of str): The keys of the first row, aschoice_keyschose them.labels(list of str): The text of each button of the second row. Keyword-only.
Returns
- list of str: A key for each button; “” for one that has none.
Examples
>>> second_row_keys(["1", "2", "3"], labels=["root position", "1st inversion"])
['A', 'S']
>>> second_row_keys(["C", "Shift+C"], labels=["3", "4", "5"])
['3', '4', '5']
note_name
def note_name(
note: Note,
*,
key: int | None = None,
minor: bool = False,
) -> str
Return a note’s name as it is written, with its octave: F♯4.
Parameters
note(Note): The note.key(int or None, default None): The major key signature for scale degrees. Without a key context, degrees fall back to letter names. Keyword-only.minor(bool, default False): Use natural minor scale degrees. Keyword-only.
Returns
- str: The name in the naming the app is set to, then the octave number.
Examples
>>> note_name(Note.parse("F#4"))
'F♯4'
note_words
def note_words(
note: Note,
*,
key: int | None = None,
minor: bool = False,
) -> str
Return a note’s name in words, for a screen reader: “F sharp 4”.
Parameters
note(Note): The note.key(int or None, default None): The major key signature for scale degrees. Without a key context, use letter names. Keyword-only.minor(bool, default False): Use natural minor scale degrees. Keyword-only.
Returns
- str: The letter, then “sharp”, “flat” or “natural” if it has a sign, then the octave number.
Examples
>>> note_words(Note.parse("F#4")), note_words(Note.parse("Bb3")), note_words(Note.parse("C4"))
('F sharp 4', 'B flat 3', 'C 4')
ExerciseView
ExerciseView(
exercise: Exercise,
*,
rng: random.Random | None = None,
parent: QWidget | None = None,
learner: Learner | None = None,
)
Bases: QWidget
The screen for practicing one exercise.
Attributes
PANE_WIDTH(int): The width of the settings pane when it is open, in pixels.REFERENCE_WIDTH(int): The width of the reference pane when it is open, in pixels.exercise(Exercise): The exercise being practiced.learner(Learner or None): Records every answer and chooses what to ask next; None asks at random.rng(random.Random): The random number generator for new questions.correct(int): Questions answered right on the first try.total(int): Questions answered.streak(int): Right answers in a row.question(Question or None): The question on screen.answered(bool): True once this showing is finished, including a miss in SM-2 or FSRS.missed(bool): True once the question has been answered wrong, so it no longer counts toward the score.buttons(list of QPushButton): The answer buttons on screen.settings_panel(ExerciseSettingsPanel): The exercise’s settings, including how to advance after a correct answer.staff(StaffWidget): Shows the notes of a question.keyboard(KeyboardWidget): Shows the key of a keyboard question.input_staff(StaffInput): The staff to click, for “place this note” questions.clef_input(ClefInput): The blank staff a clef is put on, for “place this clef” questions.scale_input(ScaleInput): The staff to click, for “place the notes of this scale” questions.fork(KeyFork): The fork to pick a key signature on, for “build this key signature” questions.answer_button(QPushButton): Hands in what was built with the fork or placed on the scale staff.book_btn(QToolButton or None): Opens the exercise’s reference in a pane on the right; None for an exercise that has none.reference_pane(QFrame or None): The pane that holds the reference.lesson_requested(Signal): Emitted with a lesson’s key when the reference pane’s lesson button is pressed.shuffle_requested(Signal): Emitted when answer feedback ends or Next is clicked during shuffled practice.
Examples
>>> from alto.exercises.library import NoteNames
>>> view = ExerciseView(NoteNames(), rng=random.Random(1))
>>> view.score.text()
'0/0 (–) streak 0'
Constructor
Build the screen and show the first question.
Parameters
exercise(Exercise): The exercise to practice.rng(random.Random or None, default None): The random number generator; a fresh one if None. Keyword-only.parent(QWidget or None, default None): The widget that owns the screen. Keyword-only.learner(Learner or None, default None): Where to record answers and what to ask next; None asks at random and records nothing. Keyword-only.
Constructor examples
>>> from alto.exercises.library import KeySignatures
>>> view = ExerciseView(KeySignatures(), rng=random.Random(2))
>>> view.settings_panel is not None # the exercise has settings behind the gear button
True
ExerciseView.hideEvent
def hideEvent(event: QHideEvent) -> None
Pause automatic advancement and answer timing while browsing another page.
Parameters
event(QHideEvent): The notification that the exercise is being hidden.
Examples
>>> from alto.exercises.library import NoteNames
>>> view = ExerciseView(NoteNames())
>>> view.show()
>>> view.hide()
>>> view._advance.isActive()
False
ExerciseView.showEvent
def showEvent(event: QShowEvent) -> None
Resume the exercise’s answer clock and pending advance when it reappears.
Parameters
event(QShowEvent): The notification that the exercise is visible again.
Examples
>>> from alto.exercises.library import NoteNames
>>> view = ExerciseView(NoteNames())
>>> view.show()
>>> view.hide()
>>> view.show()
>>> view._hidden_at is None
True
ExerciseView.settings_state
def settings_state() -> tuple[bool, int, int] | None
Remember the exercise settings pane, selected page, and scroll position before a theme rebuild.
Returns
- tuple of (bool, int, int) or None: Whether the pane is open, its page index, and its vertical scroll position; None without settings.
Examples
>>> from alto.exercises.library import NoteNames
>>> ExerciseView(NoteNames(), rng=random.Random(1)).settings_state()
(False, 0, 0)
ExerciseView.restore_settings_state
def restore_settings_state(state: tuple[bool, int, int]) -> None
Restore exercise settings navigation immediately after rebuilding the view.
Parameters
state(tuple of (bool, int, int)): Whether the pane was open, the selected page, and its vertical scroll position.
Examples
>>> from alto.exercises.library import NoteNames
>>> view = ExerciseView(NoteNames(), rng=random.Random(1))
>>> view.restore_settings_state((True, 0, 0))
>>> view.settings_state()
(True, 0, 0)
ExerciseView.scheduling_changed
def scheduling_changed() -> None
Refresh the visible exercise or invalidate its queue until it is reopened.
Examples
Lowering the daily allowance on the home page also applies to a previously opened exercise.
ExerciseView.next_question
def next_question() -> None
Show the next question: its staff, keyboard or text, and a fresh set of answer buttons.
Examples
>>> from alto.exercises.library import NoteNames
>>> view = ExerciseView(NoteNames(), rng=random.Random(1))
>>> view.next_question()
>>> # noinspection PyUnresolvedReferences
>>> view.answered, len(view.buttons) == len(view.question.choices)
(False, True)
ExerciseView.eventFilter
def eventFilter(
watched: QObject,
event: QEvent,
) -> bool
Handle staff clicks in notation questions and forward wheel turns to the fork or clef staff.
Parameters
watched(QObject): The staff or the Answer button.event(QEvent): The incoming pointer or widget event.
Returns
- bool: True when the exercise handles the event.
Examples
>>> from PySide6.QtCore import QPoint, QPointF
>>> from PySide6.QtGui import QWheelEvent
>>> from alto.exercises.library import KeySignatureConstruction
>>> view = ExerciseView(KeySignatureConstruction(), rng=random.Random(1))
>>> view.show()
>>> here = QPointF(5, 5)
>>> turn = QWheelEvent(here, here, QPoint(0, 0), QPoint(0, 120), Qt.MouseButton.NoButton,
... Qt.KeyboardModifier.NoModifier, Qt.ScrollPhase.NoScrollPhase, False)
>>> view.eventFilter(view.answer_button, turn)
True
>>> view.fork.value
1
ExerciseView.submit
def submit(
choice: str,
*,
button: QPushButton | None,
) -> None
Check an answer chosen with a button or by clicking the notation.
A correct answer uses the selected Next Question setting. An incorrect button flashes red. In SM-2 and FSRS the card returns at its scheduled retry time. ASRS and ARTS allow another answer on the same showing.
Parameters
choice(str): The text of the button that was pressed.button(QPushButton or None): The pressed button, or None for a staff click. Keyword-only.
Examples
>>> from alto.exercises.library import NoteNames
>>> sounds.enabled = False
>>> view = ExerciseView(NoteNames(), rng=random.Random(1))
>>> question = view.question
>>> # noinspection PyUnresolvedReferences
>>> wrong = next(b for b in view.buttons if b.text() != question.answer)
>>> view.submit(wrong.text(), button=wrong)
>>> view.missed, wrong.isEnabled()
(True, False)
>>> # noinspection PyUnresolvedReferences
>>> right = next(b for b in view.buttons if b.text() == question.answer)
>>> # noinspection PyUnresolvedReferences
>>> view.submit(question.answer, button=right)
>>> view.answered
True
>>> view._advance.stop()
>>> sounds.enabled = True