alto.ui.staff
The staff: lines, clefs, key signatures and notes, drawn on a rounded white “paper”.
StaffWidget draws one staff, or a grand staff with a brace, in any of the seven clefs. Notes and key signatures are
placed by their staff step (Note.diatonic) measured from the bottom line of the clef, and are engraved in the notation
font chosen in the settings.
Examples
>>> key_signature_positions("treble", sign=1)
['F5', 'C5', 'G5', 'D5', 'A4', 'E5', 'B4']
>>> staff = StaffWidget()
>>> staff.show_notes([[Note.parse("C4")]], clef="treble", key=2)
>>> staff.clef, staff.key
('treble', 2)
clef_targets
def clef_targets(clef: str) -> set[tuple[str, int]]
Return the ways a clef can be written: the symbol and where on the staff it goes.
Parameters
clef(str): A clef name such as “treble”, “mezzo” or “baritone”.
Returns
- set of tuple of (str, int): Each is a symbol, “G”, “C” or “F”, and the place of its reference line (the G, F or middle C) counted in lines and spaces up from the bottom line at 0: the bottom line is 0, the space above it 1, the second line 2, up to the top line at 8. Most clefs have one. The baritone clef has two: the F clef on the middle line and the C clef on the top line.
Examples
>>> clef_targets("treble") == {("G", 2)} and clef_targets("mezzo") == {("C", 2)}
True
>>> sorted(clef_targets("baritone"))
[('C', 8), ('F', 4)]
>>> sorted(clef_targets("french") | clef_targets("subbass"))
[('F', 8), ('G', 0)]
clef_target_of
def clef_target_of(shape: str) -> tuple[str, int]
Return the symbol and the place of one way of writing a clef.
Parameters
shape(str): A key ofengraving.CLEF_SIGNS, such as “alto” or “baritone_c”.
Returns
- tuple of (str, int): The symbol and its place, as for
clef_targets.
Examples
>>> clef_target_of("bass"), clef_target_of("soprano")
(('F', 6), ('C', 0))
draw_key_signature
def draw_key_signature(
p: QPainter,
*,
clef: str,
key: int,
x: float,
bottom: float,
gap: float,
color: QColor,
step: float = KEY_STEP,
size: float = 2.0,
font: str | None = None,
) -> None
Draw the sharps or flats of a key signature, left to right.
Parameters
p(QPainter): The painter to draw with.clef(str): The clef, which decides where on the staff each accidental goes. Keyword-only.key(int): The key signature: that many sharps if positive, flats if negative; nothing is drawn for 0. Keyword-only.x(float): The left edge of the first accidental, in pixels. Keyword-only.bottom(float): The y position of the staff’s bottom line, in pixels. Keyword-only.gap(float): The distance between staff lines, in pixels. Keyword-only.color(QColor): The color to draw in. Keyword-only.step(float, default KEY_STEP): The horizontal spacing between accidentals. Keyword-only.size(float, default 2.0): The size of the built-in characters, in staff gaps. Keyword-only.font(str or None, default None): A SMuFL font to engrave them in; None uses the built-in sharp and flat characters. Keyword-only.
Examples
>>> from PySide6.QtGui import QImage
>>> image = QImage(200, 120, QImage.Format.Format_ARGB32)
>>> image.fill(QColor("white"))
>>> painter = QPainter(image)
>>> draw_key_signature(painter, clef="treble", key=3, x=10, bottom=80, gap=12, color=QColor("black"), font="bravura")
>>> painter.end()
True
>>> any(image.pixelColor(x_, y_).lightness() < 128 for x_ in range(10, 60) for y_ in range(20, 100))
True
draw_signature_sign
def draw_signature_sign(
p: QPainter,
*,
sign: int,
x: float,
y: float,
gap: float,
color: QColor,
step: float = KEY_STEP,
size: float = 2.0,
font: str | None = None,
) -> None
Draw one sharp or flat at its written position in a key signature.
Parameters
p(QPainter): Active staff painter.sign(int): Sharp (1) or flat (-1).x, y(float): Left edge and staff pitch position in pixels.gap(float): Distance between staff lines.color(QColor): Ink for this sign.step, size(float): Slot width in pixels and built-in glyph size in staff gaps.font(str or None): SMuFL font, or None for the built-in notation.
Examples
Both the printed signature and signs placed by the learner use this drawing.
StaffWidget
StaffWidget(
parent: QWidget | None = None,
*,
gap: float = 16.0,
side: float = 20.0,
note_offset: float = 100.0,
margin: float = 8.0,
compact: bool = False,
max_step: float | None = None,
lesson_layout: bool = False,
)
Bases: QWidget
A staff with notes, a clef, a key signature and, optionally, a caption.
Attributes
GAP(float): The distance between staff lines, in pixels.side(float): The space at the left and right edges.note_offset(float): Where the notes start, from the left edge.margin(float): The space kept above and below the staff for ledger lines, in gaps.compact(bool): Size the widget to fit instead of the 220 px default.max_step(float or None): The most width each column of notes may take.clef(str): The clef being drawn (“treble”, “bass”, “alto”, “tenor”, “soprano”, “mezzo”, “baritone” or “grand”).columns(list of list of Note): The notes drawn; each inner list is one chord or note.interval_voices(bool): Draw harmonic interval endpoints with their written duration and opposing stems.note_color(QColor or None): Feedback color for the highlighted notation component, or for the notes in other exercises.column_colors(dict of int to QColor): The color of particular columns of notes, by position from 0; they are drawn in these instead ofnote_color.wedges(list of str): The step between each column and the next, such as “W” or “H”, drawn as two lines rising from the notes to a point above them, with the letter over the point; “” for none there.wedge_colors(dict of int to QColor): The color of particular wedges, by position from 0. The others take the color of the note on their right, ornote_color.notation_style(NotationStyle or None): A style to use instead of the one chosen in the settings.clef_hidden(bool): Draw the staff without its clef, for a clef the learner places.key(int): The key signature drawn: sharps if positive, flats if negative.key_room(int): How many sharps or flats’ worth of room to keep for the signature at least, so that a capped staff does not change width as the signature does. 0 keeps room only for the one drawn.value(str): The note value drawn.caption(str): Text written under the staff, inside the paper.
Examples
>>> staff = StaffWidget()
>>> staff.show_notes([[Note.parse("E4")], [Note.parse("G4")]], clef="treble")
>>> len(staff.columns)
2
Constructor
Create an empty treble staff.
Parameters
parent(QWidget or None, default None): The widget that owns the staff.gap(float, default 16.0): The distance between staff lines, in pixels. Keyword-only.side(float, default 20.0): The space at the left and right edges. Keyword-only.note_offset(float, default 100.0): Where the notes start, from the left edge. Keyword-only.margin(float, default 8.0): The space kept above and below the staff for ledger lines, in gaps. Keyword-only.compact(bool, default False): Size the widget to fit instead of the 220 px default. Keyword-only.max_step(float or None, default None): The most width each column of notes may take: the staff then stops growing once its notes would be spread wider than that, so a few notes stay easy to read in a wide window. Keyword-only.lesson_layout(bool, default False): Space the excerpt by its printed symbols and wrap at note or chord boundaries. Keyword-only.
Constructor examples
>>> StaffWidget(gap=8.0, compact=True).GAP
8.0
StaffWidget.show_notes
def show_notes(
columns: list[list[Note]],
*,
clef: str = 'treble',
key: int = 0,
value: str = 'whole',
caption: str = '',
notation_target: tuple[str, int] | None = None,
locate_notation: bool = False,
notation_excerpt: str | None = None,
) -> None
Show some notes, with a clef and a key signature.
Parameters
columns(list of list of Note): The notes: each inner list is one note or chord, drawn left to right.clef(str, default “treble”): The clef, or “grand” for a grand staff. Keyword-only.key(int, default 0): The key signature: that many sharps if positive, flats if negative. Keyword-only.value(str, default “whole”): The written duration for single notes and interval voices. Keyword-only.caption(str, default ““): Text to write under the staff. Keyword-only.notation_target(tuple of (str, int) or None): Part and position to highlight in a notation question. Keyword-only.notation_excerpt(str or None): Versioned score to show for a repertoire question. Keyword-only.locate_notation(bool, default False): Render the target in ordinary ink for the learner to find. Keyword-only.
Examples
>>> staff = StaffWidget()
>>> staff.show_notes([[Note.parse("C4")]], clef="bass", key=-1, value="quarter", caption="_ Major")
>>> staff.clef, staff.key, staff.value, staff.caption
('bass', -1, 'quarter', '_ Major')
StaffWidget.sizeHint
def sizeHint() -> QSize
Return the size the staff would like.
A capped staff asks for its full capped width, so a layout that centers it gives it that much.
Returns
- QSize: The capped width and minimum height for a lesson or a staff with a
max_step. Other staves use Qt’s default.
Examples
>>> staff = StaffWidget(max_step=120.0)
>>> staff.show_notes([[Note.parse("C4")]])
>>> staff.sizeHint().width()
500
StaffWidget.resizeEvent
def resizeEvent(event: QResizeEvent) -> None
Reflow a lesson excerpt when its available width changes.
Parameters
event(QResizeEvent): Previous and current widget size.
Examples
>>> staff = StaffWidget(lesson_layout=True)
>>> staff.resize(300, staff.height())
StaffWidget.highlight_column
def highlight_column(index: int | None) -> None
Highlight a sounding note or chord, preserving the staff’s other markings.
Parameters
index(int or None): The sounding column, or None to restore its usual ink.
Examples
>>> staff = StaffWidget()
>>> staff.highlight_column(0)
>>> staff.playback_column
0
StaffWidget.set_note_color
def set_note_color(color: QColor | None) -> None
Apply feedback to the highlighted notation component or to the notes when there is no component target.
Parameters
color(QColor or None): The feedback color. None restores the usual ink and highlight colors.
Examples
>>> staff = StaffWidget()
>>> staff.set_note_color(QColor("#2e7d32"))
>>> # noinspection PyUnresolvedReferences
>>> staff.note_color.name()
'#2e7d32'
>>> staff.set_note_color(None)
>>> staff.note_color is None
True
StaffWidget.staff_bottoms
def staff_bottoms() -> dict[str, float]
Return where each staff is drawn.
Returns
- dict of str to float: Clef name to the y position of that staff’s bottom line, in pixels. A grand staff has a “treble” and a “bass”.
Examples
>>> staff = StaffWidget()
>>> staff.resize(400, 400)
>>> staff.staff_bottoms()
{'treble': 232.0}
StaffWidget.paintEvent
def paintEvent(_: QPaintEvent) -> None
Draw the paper, the staff lines, the clef, the key signature, the notes and the caption.
Parameters
_(QPaintEvent): The paint request; the whole widget is always redrawn.
Examples
>>> staff = StaffWidget()
>>> staff.resize(400, 400)
>>> staff.show_notes([[Note.parse("C4")]], clef="treble")
>>> staff.grab().toImage().pixelColor(200, 5).name() # the white paper
'#ffffff'
StaffWidget.mouseMoveEvent
def mouseMoveEvent(event: QMouseEvent) -> None
Preview the component under the pointer in Click on Staff questions.
Parameters
event(QMouseEvent): The pointer position relative to the score.
Examples
>>> StaffWidget().hasMouseTracking()
False
StaffWidget.leaveEvent
def leaveEvent(event: QEvent) -> None
Clear the component preview when the pointer leaves the music.
Parameters
event(QEvent): The pointer leaving the staff.
Examples
>>> StaffWidget().leaveEvent(QEvent(QEvent.Type.Leave))
StaffWidget.hits_notation
def hits_notation(point: QPoint) -> bool
Check for target ink within four logical pixels of a click on the score.
Parameters
point(QPoint): Click position relative to the staff widget.
Returns
- bool: Whether the clicked neighborhood contains the selected marking.
Examples
>>> StaffWidget().hits_notation(QPoint(0, 0))
False