Alto
latest

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 of engraving.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))

key_signature_positions

def key_signature_positions(
    clef: str,
    *,
    sign: int,
) -> list[str]

Return the notes the sharps or flats of a key signature are written on, in a clef.

Each accidental is a fourth up or a fifth down from the one before (sharps: F C G D A E B, flats: B E A D G C F), and the pattern is chosen so that all seven stay on the staff, or one step above or below it. This gives the usual signatures for the treble, bass, alto and tenor clefs, and works out the rest.

Parameters

  • clef (str): A key of BOTTOM_LINE.
  • sign (int): 1 for sharps, -1 for flats. Keyword-only.

Returns

  • list of str: Seven note names with octaves, in the order the accidentals appear.

Raises

  • ValueError: If no placement keeps all seven accidentals on the staff.

Examples

>>> key_signature_positions("treble", sign=1)
['F5', 'C5', 'G5', 'D5', 'A4', 'E5', 'B4']
>>> key_signature_positions("bass", sign=-1)
['B2', 'E3', 'A2', 'D3', 'G2', 'C3', 'F2']

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 colour 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

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,
)

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.
  • note_color (QColor or None): The colour of the notes; None draws them in the notation style’s ink.
  • column_colors (dict of int to QColor): The colour of particular columns of notes, by position from 0; they are drawn in these instead of note_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 colour of particular wedges, by position from 0. The others take the colour of the note on their right, or note_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.

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 = '',
) -> 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 note value to draw (stems are only drawn for single notes). Keyword-only.
  • caption (str, default ““): Text to write under the staff. 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 centres it gives it that much.

Returns

  • QSize: The capped width and the minimum height for a staff with a max_step; otherwise Qt’s default.

Examples

>>> staff = StaffWidget(max_step=120.0)
>>> staff.show_notes([[Note.parse("C4")]])
>>> staff.sizeHint().width()
500

StaffWidget.set_note_color

def set_note_color(color: QColor | None) -> None

Draw the notes in a colour, for feedback, or back in the style’s ink.

Parameters

  • color (QColor or None): The colour; None to use the notation style’s ink.

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'