Alto
latest

alto.ui.reference

The reference pane: an interactive circle of fifths to look things up on, with an explanation under it.

Click a key on either ring, or move with the arrow keys, and the circle lights that key’s chords, shows its key signature in the middle, and the text underneath explains it.

Examples

>>> circle = ExplorableCircle()
>>> circle.select("outer", place=2)
>>> circle.title, circle.signature
('D major', 2)

ExplorableCircle

ExplorableCircle(parent: QWidget | None = None)

Bases: FifthsCircle

A circle of fifths that shows every key and lets you pick one.

Attributes

  • cell (tuple of (str, int) or None): The cell that is picked: its ring (“outer” or “inner”) and its place clockwise from the top; None for none.
  • hover (tuple of (str, int) or None): The cell under the pointer.
  • interactive (bool): Whether the circle answers the mouse and the keys. A picture of the circle that only the program changes has it off.
  • picked (Signal): Emitted with the ring and place when a cell is picked, or with “” and -1 when the pick is cleared.

Examples

>>> circle = ExplorableCircle()
>>> circle.cell, circle.title
(None, 'Circle of fifths')

Constructor

Build the circle with every key named and none picked.

Parameters

  • parent (QWidget or None, default None): The widget that owns it.

Constructor examples

>>> ExplorableCircle().shown["inner"] == set(range(12))
True

ExplorableCircle.set_interactive

def set_interactive(interactive: bool) -> None

Let the circle be clicked and moved with the keys, or make it a picture.

Parameters

  • interactive (bool): True to answer the mouse and the keys.

Examples

>>> circle = ExplorableCircle()
>>> circle.set_interactive(False)
>>> circle.interactive, circle.focusPolicy() == Qt.FocusPolicy.NoFocus
(False, True)

ExplorableCircle.clear

def clear() -> None

Pick nothing: every key is named, none is lit and the middle says what to do.

Examples

>>> circle = ExplorableCircle()
>>> circle.select("outer", place=4)
>>> circle.clear()
>>> circle.cell, circle.signature, circle.lit
(None, None, set())

ExplorableCircle.select

def select(
    ring: str,
    *,
    place: int,
) -> None

Pick a cell: light the chords of its key, and show its name and key signature in the middle.

A minor key has the key signature, and the chords, of its relative major.

Parameters

  • ring (str): “outer” for the major key at the place, “inner” for its relative minor.
  • place (int): The place, clockwise from the top. Keyword-only.

Examples

>>> circle = ExplorableCircle()
>>> circle.select("inner", place=3)
>>> circle.title, circle.subtitle, sorted(circle.lit), circle.numerals[("outer", 4)]
('F♯ minor', '3 sharps', [2, 3, 4], 'V')

ExplorableCircle.cell_at

def cell_at(point: QPointF) -> tuple[str, int] | None

Return the cell under a point.

Parameters

  • point (QPointF): A position in the widget.

Returns

  • tuple of (str, int) or None: The ring and place, or None for the middle disc or outside the circle.

Examples

>>> circle = ExplorableCircle()
>>> circle.resize(400, 400)
>>> middle, size = circle.geometry_of()
>>> circle.cell_at(QPointF(middle.x(), middle.y() - 0.9 * size))
('outer', 0)
>>> circle.cell_at(QPointF(middle.x() + 0.6 * size, middle.y()))
('inner', 3)
>>> circle.cell_at(middle) is None
True

ExplorableCircle.lift_of

def lift_of(
    ring: str,
    *,
    place: int,
) -> float

Return how bright a cell is drawn: as for any question, and a little brighter under the pointer.

Parameters

  • ring (str): “outer” or “inner”.
  • place (int): The place clockwise from the top. Keyword-only.

Returns

  • float: The brightness, from 0 to 1.

Examples

>>> circle = ExplorableCircle()
>>> circle.hover = ("outer", 5)
>>> circle.lift_of("outer", place=5), circle.lift_of("outer", place=6)
(0.2, 0.0)

ExplorableCircle.mousePressEvent

def mousePressEvent(event: QMouseEvent) -> None

Pick the cell that is clicked; a click in the middle clears the pick.

Parameters

  • event (QMouseEvent): The click.

Examples

>>> from PySide6.QtCore import QPoint
>>> from PySide6.QtTest import QTest
>>> circle = ExplorableCircle()
>>> circle.resize(400, 400)
>>> centre, radius = circle.geometry_of()
>>> QTest.mouseClick(circle, Qt.MouseButton.LeftButton, pos=QPoint(int(centre.x()), int(centre.y() - 0.9 * radius)))
>>> circle.cell
('outer', 0)

ExplorableCircle.mouseMoveEvent

def mouseMoveEvent(event: QMouseEvent) -> None

Light the cell under the pointer, and show a hand over the ones that can be picked.

Parameters

  • event (QMouseEvent): The move.

Examples

>>> from PySide6.QtCore import QPoint
>>> from PySide6.QtTest import QTest
>>> circle = ExplorableCircle()
>>> circle.resize(400, 400)
>>> circle.show()
>>> centre, radius = circle.geometry_of()
>>> QTest.mouseMove(circle, QPoint(int(centre.x()), int(centre.y() - 0.9 * radius)))
>>> circle.hover
('outer', 0)

ExplorableCircle.leaveEvent

def leaveEvent(event: QEvent) -> None

Stop lighting a cell once the pointer has left.

Parameters

  • event (QEvent): The event.

Examples

>>> circle = ExplorableCircle()
>>> circle.hover = ("outer", 1)
>>> circle.leaveEvent(QEvent(QEvent.Type.Leave))
>>> circle.hover is None
True

ExplorableCircle.keyPressEvent

def keyPressEvent(event: QKeyEvent) -> None

Move the pick with the arrow keys: Left and Right round the circle, Up and Down between the rings.

Escape clears the pick, and Home picks C major.

Parameters

  • event (QKeyEvent): The key.

Examples

>>> circle = ExplorableCircle()
>>> press = QKeyEvent(QKeyEvent.Type.KeyPress, Qt.Key.Key_Right, Qt.KeyboardModifier.NoModifier)
>>> circle.keyPressEvent(press)
>>> circle.cell
('outer', 0)
>>> circle.keyPressEvent(press)
>>> circle.cell
('outer', 1)

ReferencePanel

ReferencePanel(parent: QWidget | None = None)

Bases: QWidget

The reference for the circle of fifths: a short description, the circle to explore, and what the picked key means.

Attributes

  • circle (ExplorableCircle): The circle to pick a key on.
  • explanation (QLabel): The text under the circle, which follows the pick.
  • lesson_button (QPushButton): Opens the lesson on the circle of fifths.
  • lesson_requested (Signal): Emitted with the key of the lesson to open when that button is pressed.

Examples

>>> panel = ReferencePanel()
>>> panel.circle.select("outer", place=1)
>>> "<b>G major</b>" in panel.explanation.text()
True

Constructor

Build the panel with nothing picked.

Parameters

  • parent (QWidget or None, default None): The widget that owns it.

Constructor examples

>>> panel = ReferencePanel()
>>> panel.explanation.text() == ""
False

ClefReferencePanel

ClefReferencePanel(parent: QWidget | None = None)

Bases: QWidget

The reference for the clefs: how they are made, and a picture of each with where its symbol goes.

Attributes

  • lesson_button (QPushButton): Opens the lesson on the clefs.
  • lesson_requested (Signal): Emitted with the key of the lesson to open when that button is pressed.
  • rows (dict of str to QLabel): The words beside the picture of each clef, by clef.

Examples

>>> panel = ClefReferencePanel()
>>> "C clef" in panel.rows["mezzo"].text() and "bottom line" in panel.rows["french"].text()
True

Constructor

Build the panel: the lesson button, a line of explanation and a row for each clef.

Parameters

  • parent (QWidget or None, default None): The widget that owns it.

Constructor examples

>>> len(ClefReferencePanel().rows) == len(settings.CLEF_BASICS_CLEFS)
True

reference_panel_for

def reference_panel_for(exercise: Exercise) -> ReferencePanel | ClefReferencePanel | None

Return the reference pane for an exercise.

Parameters

  • exercise (Exercise): The exercise.

Returns

  • ReferencePanel or ClefReferencePanel or None: The panel, or None for an exercise with nothing to look up.

Examples

>>> from alto.exercises.library import NoteNames
>>> reference_panel_for(NoteNames()) is None, reference_panel_for(CircleOfFifths()) is not None
(True, True)
>>> type(reference_panel_for(ClefBasics())).__name__
'ClefReferencePanel'