alto.ui.key_fork
The fork: a picker for a key signature, shaped like a tuning fork lying on its side.
The stem on the left ends in a natural sign (no sharps or flats, C major). At the right the stem opens into two tines: the top one has the sharps, 1 to 7, and the bottom one the flats, 1 to 7. A circle marks the chosen signature. Click a number to choose it, drag the circle along the fork, or turn the mouse wheel to move it.
Examples
>>> fork = KeyFork()
>>> fork.set_value(-3)
>>> fork.value
-3
node_position
def node_position(value: int) -> QPointF
Return where a signature sits on the fork.
Parameters
value(int): The signature: that many sharps if positive (top tine), flats if negative (bottom tine), 0 for the stem’s end.
Returns
- QPointF: The centre of its number, in the widget’s coordinates.
Examples
>>> node_position(0).x() < node_position(1).x() < node_position(2).x()
True
>>> node_position(3).y() < node_position(0).y() < node_position(-3).y()
True
route
def route(value: int) -> list[QPointF]
Return the way along the fork from the end of the stem to a signature.
Parameters
value(int): The signature, as fornode_position.
Returns
- list of QPointF: The points to pass through: the stem’s end, round the bend of the U to the tine and then each number up to the one asked.
Examples
>>> len(route(0)), len(route(2)) > len(route(1)) > len(route(0))
(1, True)
>>> route(-1)[-1] == node_position(-1)
True
>>> round(route(3)[1].x()) == round(APEX_X) # it leaves the stem at the apex of the U
True
path_between
def path_between(
a: int,
*,
b: int,
) -> list[QPointF]
Return the way along the fork from one signature to another.
The circle goes back along the tine it is on, round the U and out along the other, never across the gap between the tines.
Parameters
a(int): The signature to start from.b(int): The signature to end at. Keyword-only.
Returns
- list of QPointF: The points to pass through, from
atob.
Examples
>>> path_between(2, b=2) == [node_position(2)]
True
>>> path_between(1, b=-1)[0] == node_position(1) and path_between(1, b=-1)[-1] == node_position(-1)
True
>>> any(abs(p.x() - APEX_X) < 1e-9 for p in path_between(1, b=-1)) # it goes round the U, through its apex
True
point_along
def point_along(
points: list[QPointF],
*,
t: float,
) -> QPointF
Return the point a fraction of the way along a path made of short straight pieces.
Parameters
points(list of QPointF): The corners of the path; at least one.t(float): How far along, from 0 (the first point) to 1 (the last). Keyword-only.
Returns
- QPointF: The point that far along.
Examples
>>> point_along([QPointF(0, 0), QPointF(10, 0), QPointF(10, 10)], t=0.75).toTuple()
(10.0, 5.0)
>>> point_along([QPointF(0, 0), QPointF(3, 4)], t=0.5).toTuple() # slanting pieces are measured along their length
(1.5, 2.0)
nearest_on_fork
def nearest_on_fork(point: QPointF) -> QPointF
Return the point on the fork’s line that is closest to a point.
Parameters
point(QPointF): Any position in the widget, such as the mouse while the circle is dragged.
Returns
- QPointF: The closest point on the way from the last sharp, round the U, to the last flat.
Examples
>>> nearest_on_fork(QPointF(node_position(2).x(), 0)) == node_position(2) # straight above the number
True
>>> nearest_on_fork(QPointF(-50, node_position(0).y())) == node_position(0) # past the end of the stem
True
fork_path
def fork_path() -> QPainterPath
Return the outline of the fork: the stem, a half circle for the U, and the two tines.
Returns
- QPainterPath: One smooth line, drawn from the end of the stem.
Examples
>>> outline = fork_path()
>>> outline.boundingRect().left() == STEM_X and outline.boundingRect().top() == TOP_Y
True
draw_natural
def draw_natural(
p: QPainter,
*,
center: QPointF,
height: float,
color: QColor,
) -> None
Draw a natural sign: two upright lines joined by two slanting bars.
Parameters
p(QPainter): The painter to draw with.center(QPointF): The middle of the sign. Keyword-only.height(float): How tall it is, in pixels. Keyword-only.color(QColor): The colour of the lines. Keyword-only.
Examples
>>> from PySide6.QtGui import QPixmap
>>> canvas = QPixmap(20, 20)
>>> painter = QPainter(canvas)
>>> draw_natural(painter, center=QPointF(10, 10), height=14, color=QColor("black"))
>>> _ = painter.end()
KeyFork
KeyFork(
*,
parent: QWidget | None = None,
)
Bases: QWidget
A tuning fork on its side, for choosing how many sharps or flats a key signature has.
Attributes
value(int): The chosen signature: sharps if positive, flats if negative, 0 for none.locked(bool): While True the fork ignores the mouse and the keyboard.changed(Signal): Emitted with the newvaluewhenever it changes.
Examples
>>> fork = KeyFork()
>>> got = []
>>> _ = fork.changed.connect(got.append)
>>> fork.set_value(2)
>>> fork.set_value(2) # no change, nothing said
>>> got
[2]
Constructor
Build the fork, set to no sharps or flats.
Parameters
parent(QWidget or None, default None): The widget that owns the fork. Keyword-only.
Constructor examples
>>> KeyFork().value
0
KeyFork.set_value
def set_value(
value: int,
*,
slide: bool = True,
) -> None
Choose a signature and move the circle to it.
Parameters
value(int): The signature, kept between 7 flats and 7 sharps.slide(bool, default True): Move the circle along the fork; if False it jumps. Keyword-only.
Examples
>>> fork = KeyFork()
>>> fork.set_value(99)
>>> fork.value
7
>>> fork.set_value(0, slide=False)
>>> fork.value, fork._marker == node_position(0)
(0, True)
KeyFork.set_marker_color
def set_marker_color(color: QColor | None) -> None
Colour the circle, for a right or wrong answer.
Parameters
color(QColor or None): The colour to use, or None for the highlight colour.
Examples
>>> fork = KeyFork()
>>> fork.set_marker_color(QColor("#2e7d32"))
>>> fork._marker_color == QColor("#2e7d32")
True
KeyFork.value_at
@staticmethod
def value_at(point: QPointF) -> int | None
Return the signature whose number is under a point.
Parameters
point(QPointF): A position in the widget.
Returns
- int or None: The signature there, or None if the point is not near a number.
Examples
>>> fork = KeyFork()
>>> fork.value_at(node_position(3)), fork.value_at(node_position(-4)), fork.value_at(node_position(0))
(3, -4, 0)
>>> fork.value_at(QPointF(5, 130)) is None
True
KeyFork.mousePressEvent
def mousePressEvent(event: QMouseEvent) -> None
Pick up the circle if it was pressed, or choose the number that was clicked.
Parameters
event(QMouseEvent): The press. Only the left button does anything.
Examples
>>> from PySide6.QtCore import QEvent
>>> fork = KeyFork()
>>> point = node_position(-2)
>>> fork.mousePressEvent(QMouseEvent(QEvent.Type.MouseButtonPress, point, point, Qt.MouseButton.LeftButton,
... Qt.MouseButton.LeftButton, Qt.KeyboardModifier.NoModifier))
>>> fork.value
-2
KeyFork.mouseMoveEvent
def mouseMoveEvent(event: QMouseEvent) -> None
Carry the circle along the fork while it is held, and light the number under the mouse otherwise.
The signature changes to the nearest number as the circle passes it.
Parameters
event(QMouseEvent): The move.
Examples
>>> from PySide6.QtCore import QEvent
>>> fork = KeyFork()
>>> here = node_position(0)
>>> there = node_position(3)
>>> fork.mousePressEvent(QMouseEvent(QEvent.Type.MouseButtonPress, here, here, Qt.MouseButton.LeftButton,
... Qt.MouseButton.LeftButton, Qt.KeyboardModifier.NoModifier))
>>> fork.mouseMoveEvent(QMouseEvent(QEvent.Type.MouseMove, there, there, Qt.MouseButton.NoButton,
... Qt.MouseButton.LeftButton, Qt.KeyboardModifier.NoModifier))
>>> fork.value
3
KeyFork.mouseReleaseEvent
def mouseReleaseEvent(event: QMouseEvent) -> None
Let go of the circle, which slides to the number it is nearest.
Parameters
event(QMouseEvent): The release.
Examples
>>> from PySide6.QtCore import QEvent
>>> fork = KeyFork()
>>> fork._dragging = True
>>> fork._marker = node_position(0) + QPointF(9, 0)
>>> fork.mouseReleaseEvent(QMouseEvent(QEvent.Type.MouseButtonRelease, fork._marker, fork._marker,
... Qt.MouseButton.LeftButton, Qt.MouseButton.NoButton,
... Qt.KeyboardModifier.NoModifier))
>>> fork._dragging
False
KeyFork.leaveEvent
def leaveEvent(event: QEvent) -> None
Stop lighting a number when the mouse leaves the fork.
Parameters
event(QEvent): The leave event.
Examples
>>> fork = KeyFork()
>>> fork._hover = 3
>>> fork.leaveEvent(QEvent(QEvent.Type.Leave))
>>> fork._hover is None
True
KeyFork.wheelEvent
def wheelEvent(event: QWheelEvent) -> None
Move the circle one number along the fork for each notch of the wheel.
Rolling up goes towards more sharps and down towards more flats, passing through the natural sign.
Parameters
event(QWheelEvent): The wheel turn.
Examples
>>> from PySide6.QtCore import QPoint
>>> fork = KeyFork()
>>> point = QPointF(100, 50)
>>> fork.wheelEvent(QWheelEvent(point, point, QPoint(0, 0), QPoint(0, -120), Qt.MouseButton.NoButton,
... Qt.KeyboardModifier.NoModifier, Qt.ScrollPhase.NoScrollPhase, False))
>>> fork.value
-1
KeyFork.keyPressEvent
def keyPressEvent(event: QKeyEvent) -> None
Move the circle with the arrow keys: up or right for a sharp, down or left for a flat.
Parameters
event(QKeyEvent): The key press.
Examples
>>> from PySide6.QtCore import QEvent
>>> fork = KeyFork()
>>> fork.keyPressEvent(QKeyEvent(QEvent.Type.KeyPress, Qt.Key.Key_Up, Qt.KeyboardModifier.NoModifier))
>>> fork.value
1
KeyFork.paintEvent
def paintEvent(_: QPaintEvent) -> None
Draw the fork, its numbers and the circle on the chosen one.
Parameters
_(QPaintEvent): The paint request; the whole widget is always redrawn.
Examples
>>> KeyFork().grab().isNull()
False