alto.ui.circle
The circle of fifths: twelve wedges, the major keys on the outside and their relative minors on the inside.
C is at the top and each step clockwise is a fifth up, so the keys gather sharps on the right and flats on the left. The disc in the middle shows the staff and key signature of the key being talked about. In an exercise one wedge is the question and its name (or its Roman numeral) is blank until the answer is right.
Examples
>>> circle = FifthsCircle()
>>> circle.show_question("major", place=3, title="F♯ minor")
>>> circle.target
('outer', 3)
wedge_path
def wedge_path(
*,
centre: QPointF,
inner: float,
outer: float,
index: int,
) -> QPainterPath
Return the outline of one wedge of a ring.
Parameters
centre(QPointF): The middle of the circle.inner(float): The radius of the wedge’s inner edge, in pixels. Keyword-only.outer(float): The radius of its outer edge. Keyword-only.index(int): Which wedge: 0 is the one at the top and they go clockwise. Keyword-only.
Returns
- QPainterPath: A closed shape, a piece of a ring 30 degrees wide.
Examples
>>> shape = wedge_path(centre=QPointF(100, 100), inner=40, outer=90, index=0)
>>> shape.contains(QPointF(100, 30)), shape.contains(QPointF(100, 170)) # the top of the circle, and the bottom
(True, False)
wedge_middle
def wedge_middle(
*,
centre: QPointF,
radius: float,
index: int,
) -> QPointF
Return the point in the middle of a wedge, at a given distance from the centre.
Parameters
centre(QPointF): The middle of the circle.radius(float): How far out, in pixels. Keyword-only.index(int): Which wedge, clockwise from the top. Keyword-only.
Returns
- QPointF: The point.
Examples
>>> wedge_middle(centre=QPointF(100, 100), radius=50, index=0).toTuple() # straight up
(100.0, 50.0)
>>> round(wedge_middle(centre=QPointF(100, 100), radius=50, index=3).x()) # a quarter of the way round: to the right
150
wedge_color
def wedge_color(
index: int,
*,
inner: bool,
lift: float = 0.0,
scheme: Scheme | None = None,
) -> QColor
Return the colour of a wedge in a colour scheme: quiet when it is not being talked about and bright when it is.
Parameters
index(int): Which wedge, clockwise from the top.inner(bool): Whether it is in the inner ring. Keyword-only.lift(float, default 0.0): How bright it is, from 0 (quiet) to 1 (lit). Keyword-only.scheme(Scheme or None, default None): The colour scheme; the one chosen in the circle of fifths settings if None. Keyword-only.
Returns
- QColor: The colour.
Examples
>>> from alto.circle_schemes import preset
>>> spectrum = preset("spectrum")
>>> wedge_color(0, inner=False, lift=1.0, scheme=spectrum).hue(), wedge_color(6, inner=False, scheme=spectrum).hue()
(0, 180)
>>> lit, quiet = (wedge_color(0, inner=False, lift=amount, scheme=spectrum) for amount in (1.0, 0.0))
>>> lit.lightness() > quiet.lightness()
True
>>> # no wedge looks too bright for white names
>>> every = [wedge_color(i, inner=False, lift=1.0, scheme=spectrum) for i in range(12)]
>>> all(0.299 * c.redF() + 0.587 * c.greenF() + 0.114 * c.blueF() <= 0.44 for c in every)
True
write_text
def write_text(
p: QPainter,
*,
centre: QPointF,
text: str,
pixels: float,
weight: QFont.Weight,
colour: QColor,
max_width: float | None = None,
) -> None
Write a line of text centred on a point, with its sharps and flats drawn as the notation font draws them.
The letters are in the app’s own font. Its ♭ is the shape of a small “b”, though, and does not look like a flat sign, so the sharps, flats and naturals are the glyphs of the notation style that the staff is drawn in, sized to the letters.
Parameters
p(QPainter): The painter to draw with.centre(QPointF): The middle of the line. Keyword-only.text(str): What to write, such as “B♭m” or “F♯ major”. Keyword-only.pixels(float): The size of the letters. Keyword-only.weight(QFont.Weight): How heavy they are. Keyword-only.colour(QColor): The colour. Keyword-only.max_width(float or None, default None): The widest the line may be. A longer line is written smaller to fit. Keyword-only.
Examples
>>> from PySide6.QtGui import QImage
>>> image = QImage(120, 60, QImage.Format.Format_ARGB32)
>>> image.fill(QColor("black"))
>>> painter = QPainter(image)
>>> write_text(painter, centre=QPointF(60, 30), text="B♭m", pixels=24, weight=QFont.Weight.Bold, colour=QColor("white"))
>>> painter.end()
True
>>> any(image.pixelColor(x, 30).lightness() > 128 for x in range(20, 100))
True
FifthsCircle
FifthsCircle(parent: QWidget | None = None)
Bases: QWidget
The circle of fifths, drawn for an exercise.
Attributes
kind(str): What is being asked: “major”, “minor” or “numeral”, or “” for nothing.target(tuple of (str, int) or None): The cell asked about: its ring (“outer” or “inner”) and its place clockwise from the top.shown(dict of str to set of int): For each ring, the places whose key name is written.lit(set of int): The places of the chords of the key, in a Roman numeral question; both rings are lit there.numerals(dict of tuple of (str, int) to str): The Roman numeral written in each cell that has one.title(str): The big text in the middle.subtitle(str): The small text in the middle.signature(int or None): The key signature drawn on the staff in the middle, or None for no staff.
Examples
>>> circle = FifthsCircle()
>>> circle.show_question("major", place=0, title="A minor")
>>> circle.reveal(animate=False)
>>> circle.shown["outer"], circle.signature
({0}, 0)
Constructor
Build the circle, with nothing asked.
Parameters
parent(QWidget or None, default None): The widget that owns it.
Constructor examples
>>> FifthsCircle().target is None
True
FifthsCircle.sizeHint
def sizeHint() -> QSize
Return the size it would like: a square, big enough to read.
Returns
- QSize: The size.
Examples
>>> FifthsCircle().sizeHint().width()
460
FifthsCircle.show_question
def show_question(
kind: str,
*,
place: int,
title: str,
ring: str | None = None,
key: int | None = None,
) -> None
Ask about a cell, showing what the question needs and leaving the answer blank.
A “major” question shows the minor keys and asks for the major of one of them; a “minor” question shows the majors and asks for a minor; a “numeral” question shows every name, lights the six chords of a key with its staff in the middle, and asks for the Roman numeral of one of them.
Parameters
kind(str): “major”, “minor” or “numeral”.place(int): The place of the cell asked about, clockwise from the top. Keyword-only.title(str): The big text in the middle, such as “F♯ minor”. Keyword-only.ring(str or None, default None): The ring of the cell asked about; for “major” the outer one and for “minor” the inner one if None. Keyword-only.key(int or None, default None): For a “numeral” question, the place of the key whose chords they are. Keyword-only.
Examples
>>> circle = FifthsCircle()
>>> circle.show_question("minor", place=3, title="A major")
>>> circle.target, circle.shown["outer"] == set(range(12)), circle.shown["inner"], circle.signature
(('inner', 3), True, set(), None)
>>> circle.show_question("numeral", place=11, ring="outer", key=0, title="C major")
>>> sorted(circle.lit), circle.signature, circle.numerals
([0, 1, 11], 0, {})
FifthsCircle.reset
def reset() -> None
Clear everything: no question, no names shown, no animation running.
Examples
>>> circle = FifthsCircle()
>>> circle.show_question("major", place=2, title="B minor")
>>> circle.reset()
>>> circle.target is None and circle.title == "" and circle.lit == set()
True
FifthsCircle.reveal
def reveal(
*,
animate: bool = True,
) -> None
Show the answer: the key’s name in its cell, brightened, and its staff and key signature in the middle.
For a Roman numeral question every chord of the key shows its numeral, as the circle in the reference does.
Parameters
animate(bool, default True): Brighten the cell gradually; if False it is bright at once. Keyword-only.
Examples
>>> circle = FifthsCircle()
>>> circle.show_question("minor", place=5, title="B major / C♭ major")
>>> circle.reveal(animate=False)
>>> circle.shown["inner"], circle.title, circle.subtitle, circle.signature
({5}, 'G♯ minor', '5 sharps', 5)
FifthsCircle.set_subtitle
def set_subtitle(text: str) -> None
Change the small text in the middle, for example to say that a second answer is wanted.
Parameters
text(str): The new text.
Examples
>>> circle = FifthsCircle()
>>> circle.set_subtitle("and its other name")
>>> circle.subtitle
'and its other name'
FifthsCircle.flash_wrong
def flash_wrong() -> None
Flash the cell asked about in the red of a wrong answer, striped as well so that it still shows on the red wedge.
Examples
>>> circle = FifthsCircle()
>>> circle.show_question("major", place=0, title="A minor")
>>> circle.flash_wrong()
>>> circle._warning is not None
True
FifthsCircle.lift_of
def lift_of(
ring: str,
*,
place: int,
) -> float
Return how bright a cell is drawn, from 0 (quiet) to 1 (fully lit).
The cell asked about is half lit, and brightens when it is answered. The cell beside it on the other ring is a little lit, to show the pair; in a Roman numeral question the six chords of the key are lit instead.
Parameters
ring(str): “outer” or “inner”.place(int): The place clockwise from the top. Keyword-only.
Returns
- float: The brightness.
Examples
>>> circle = FifthsCircle()
>>> circle.show_question("major", place=0, title="A minor")
>>> circle.lift_of("outer", place=0), circle.lift_of("inner", place=0), circle.lift_of("outer", place=5)
(0.5, 0.3, 0.0)
>>> circle.reveal(animate=False)
>>> circle.lift_of("outer", place=0)
1.0
FifthsCircle.geometry_of
def geometry_of() -> tuple[QPointF, float]
Return where the circle is drawn: its middle and its radius.
The circle fits the widget as a square in the middle of it, but no larger than MAX_RADIUS.
Returns
- tuple of QPointF and float: The centre and the radius, in pixels.
Examples
>>> circle = FifthsCircle()
>>> circle.resize(400, 300)
>>> middle, radius = circle.geometry_of()
>>> middle.toTuple(), radius < 150
((200.0, 150.0), True)
>>> circle.resize(2400, 2000)
>>> circle.geometry_of()[1] == MAX_RADIUS
True
FifthsCircle.paintEvent
def paintEvent(_: QPaintEvent) -> None
Draw the two rings, the names, the question and the disc in the middle.
Parameters
_(QPaintEvent): The paint request; the whole circle is always redrawn.
Examples
>>> circle = FifthsCircle()
>>> circle.resize(400, 400)
>>> circle.show_question("major", place=0, title="A minor")
>>> circle.grab().isNull()
False