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.
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) -> str
Return a note’s name as it is written, with its octave: F♯4.
Parameters
note(Note): The note.
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) -> str
Return a note’s name in words, for a screen reader: “F sharp 4”.
Parameters
note(Note): The note.
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 practising 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 practised.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 first time.total(int): Questions answered.streak(int): Right answers in a row.question(Question or None): The question on screen.answered(bool): True once the question has been answered right.missed(bool): True once the question has been answered wrong, so it no longer counts towards the score.buttons(list of QPushButton): The answer buttons on screen.settings_panel(QWidget or None): The exercise’s settings, or None for an exercise with none.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.
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 practise.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.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
Send the mouse wheel to the fork, or to the clef staff, while it is showing and the mouse is over the music or Answer.
Parameters
watched(QObject): The staff or the Answer button.event(QEvent): Anything that reaches it; only the wheel is taken.
Returns
- bool: True if the fork or the clef staff took the wheel turn, False to let it go on as usual.
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
Check an answer chosen with a button.
A right answer is scored, fades green, plays (unless the exercise is silent) and moves on after a moment; a wrong one fades red and its button is switched off, so another can be tried.
Parameters
choice(str): The text of the button that was pressed.button(QPushButton): The button. Nothing happens if it is switched off. 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