alto.ui.pictures
Small pictures of musical things (clefs, note values, key signatures, note ranges …) for the settings panes.
Each picture is drawn in fixed units and then scaled, so the same picture serves as a summary in a menu row and, larger, as the label of a choice. Colours come from the palette, so they work in light and dark themes.
Examples
>>> CLEF_NAMES["treble"], VALUE_NAMES["sixteenth"]
('Treble', '16th')
>>> ClefPictures(["treble", "bass"]).toolTip()
'Treble, Bass'
symbol_icon
def symbol_icon(
symbol: str,
*,
color: QColor,
height: int = 56,
) -> QIcon
Draw a clef symbol on its own, without a staff, as an icon.
The G, C and F clefs are drawn the same size as they are on a staff, so the three look alike beside one another, and centred.
Parameters
symbol(str): “G”, “C” or “F”.color(QColor): The colour to draw it in. Keyword-only.height(int, default 56): The icon’s height in pixels, which is also as wide as it is. Keyword-only.
Returns
- QIcon: The icon, in the notation font chosen in the settings.
Examples
>>> symbol_icon("F", color=QColor("black")).isNull()
False
ClefPictures
ClefPictures(
clefs: list[str] | None = None,
*,
scale: float = 1.0,
parent: QWidget | None = None,
)
Bases: _Picture
The selected clefs, each on its own five-line staff, and a two-stave picture with a brace for the grand staff.
Showing each clef on its own staff lets alto and tenor, which share a symbol, look different.
Attributes
H, W, GAP, SPACING(float): The picture’s height, the width of one clef, the distance between staff lines and the space between clefs.NAMES(dict of str to str): The name of each clef.clefs(list of str): The clefs shown.
Examples
>>> ClefPictures(["alto", "tenor"]).toolTip()
'Alto, Tenor'
Constructor
Create the picture.
Parameters
clefs(list of str or None, default None): The clefs to show, any ofCLEF_NAMES.scale(float, default 1.0): How much to enlarge it. Keyword-only.parent(QWidget or None, default None): The widget that owns it. Keyword-only.
Constructor examples
>>> ClefPictures(["treble"], scale=2.0).width()
60
ClefPictures.set_clefs
def set_clefs(clefs: list[str]) -> None
Show different clefs and size the picture for them.
Parameters
clefs(list of str): The clefs to show, any ofCLEF_NAMES.
Examples
>>> pictures = ClefPictures()
>>> pictures.set_clefs(["treble", "bass", "alto"])
>>> pictures.width() # three clefs and the space between them
106
>>> pictures.toolTip()
'Treble, Bass, Alto'
ClefPictures.icon
@classmethod
def icon(
clef: str,
*,
scale: float = 1.8,
) -> QIcon
Return one clef as an icon.
Parameters
clef(str): A key ofCLEF_NAMES.scale(float, default 1.8): How much to enlarge it. Keyword-only.
Returns
- QIcon: The icon.
Examples
>>> ClefPictures.icon("grand").isNull()
False
ClefPictures.paintEvent
def paintEvent(_: QPaintEvent) -> None
Draw each clef on its staff, or the grand staff with its brace.
Parameters
_(QPaintEvent): The paint request; the whole widget is always redrawn.
Examples
>>> ClefPictures(["treble", "grand"]).grab().isNull()
False
ValuePictures
ValuePictures(
values: list[str] | None = None,
*,
scale: float = 1.0,
centre_stemless: bool = False,
parent: QWidget | None = None,
)
Bases: _Picture
Note values as engraved symbols (no staff), each with its head on the same baseline so they line up.
Attributes
values(list of str): The note values shown, keys ofVALUE_NAMES.centre_stemless(bool): Whether the breve and whole note sit at the picture’s vertical centre.
Examples
>>> pictures = ValuePictures(["whole", "quarter", "eighth"])
>>> pictures.values
['whole', 'quarter', 'eighth']
Constructor
Create the picture.
Parameters
values(list of str or None, default None): The note values to show.scale(float, default 1.0): How much to enlarge it. Keyword-only.centre_stemless(bool, default False): Put the breve and whole note at the picture’s vertical centre, so beside a line of text they line up with the middle of the text; the others keep their heads low so their stems fit above. Keyword-only.parent(QWidget or None, default None): The widget that owns it. Keyword-only.
Constructor examples
>>> ValuePictures(["half"], centre_stemless=True).centre_stemless
True
ValuePictures.set_values
def set_values(values: list[str]) -> None
Show different note values and size the picture for them.
Parameters
values(list of str): The note values to show.
Examples
>>> pictures = ValuePictures()
>>> pictures.set_values(["breve", "whole"])
>>> pictures.values
['breve', 'whole']
ValuePictures.icon
@classmethod
def icon(
value: str,
*,
scale: float = 1.7,
) -> QIcon
Return one note value as an icon.
Parameters
value(str): A key ofVALUE_NAMES.scale(float, default 1.7): How much to enlarge it. Keyword-only.
Returns
- QIcon: The icon.
Examples
>>> ValuePictures.icon("quarter").isNull()
False
ValuePictures.paintEvent
def paintEvent(_: QPaintEvent) -> None
Draw each note value.
Parameters
_(QPaintEvent): The paint request; the whole widget is always redrawn.
Examples
>>> ValuePictures(["whole", "half", "quarter"]).grab().isNull()
False
KeySignaturePicture
KeySignaturePicture(
key: int = 0,
*,
scale: float = 1.0,
parent: QWidget | None = None,
)
Bases: _Picture
A key signature as a plain row of its sharps or flats, with no staff or clef.
Each sign sits at the height it has after a treble clef, and C major, which has none, shows a natural sign.
Attributes
H, GAP, STEP(float): The picture’s height, the distance between staff lines and the space between signs.ORDER(dict of int to str): Where each sign is written, in order, for sharps (1) and flats (-1).key(int): The key signature: sharps if positive, flats if negative.
Examples
>>> KeySignaturePicture(2).toolTip()
'D major: 2 sharps'
Constructor
Create the picture.
Parameters
key(int, default 0): The key signature: that many sharps if positive, flats if negative.scale(float, default 1.0): How much to enlarge it. Keyword-only.parent(QWidget or None, default None): The widget that owns it. Keyword-only.
Constructor examples
>>> KeySignaturePicture(0).toolTip()
'C major: no sharps or flats'
>>> KeySignaturePicture(-1).toolTip()
'F major: 1 flat'
KeySignaturePicture.icon
@classmethod
def icon(
key: int,
*,
scale: float = 1.2,
) -> QIcon
Return a key signature as an icon.
Parameters
key(int): Sharps if positive, flats if negative.scale(float, default 1.2): How much to enlarge it. Keyword-only.
Returns
- QIcon: The icon.
Examples
>>> KeySignaturePicture.icon(3).isNull()
False
KeySignaturePicture.paintEvent
def paintEvent(_: QPaintEvent) -> None
Draw the row of sharps or flats, or a natural sign for C major.
Parameters
_(QPaintEvent): The paint request; the whole widget is always redrawn.
Examples
>>> KeySignaturePicture(-3).grab().isNull()
False
RangePictures
RangePictures(
items: list[tuple[str, int, int]] | None = None,
*,
scale: float = 1.0,
max_width: float | None = None,
parent: QWidget | None = None,
)
Bases: _Picture
For each clef, a staff with its lowest and highest note, so the range can be read off at a glance.
Attributes
H, W, SPACING(float): The picture’s height, the width of one staff and the space between staves.MAX_SCALE(float): The most the picture is enlarged to fitmax_width.max_width(float or None): The width to enlarge the picture to, if any.items(list of tuple of (str, int, int)): Each clef with its lowest and highest note, as staff steps (Note.diatonic).
Examples
>>> pictures = RangePictures([("treble", 22, 52)])
>>> pictures.toolTip()
'Treble: D3 to F7'
Constructor
Create the picture.
Parameters
items(list of tuple of (str, int, int) or None, default None): Each clef with its lowest and highest note.scale(float, default 1.0): How much to enlarge it. Keyword-only.max_width(float or None, default None): Enlarge the picture to use this width (up toMAX_SCALE) however many clefs there are. Keyword-only.parent(QWidget or None, default None): The widget that owns it. Keyword-only.
Constructor examples
>>> RangePictures([("treble", 22, 52)], max_width=238).scale
1.9
RangePictures.set_items
def set_items(items: list[tuple[str, int, int]]) -> None
Show the ranges of some clefs and size the picture for them.
Parameters
items(list of tuple of (str, int, int)): Each clef with its lowest and highest note, as staff steps (Note.diatonic).
Examples
>>> pictures = RangePictures()
>>> pictures.set_items([("bass", 10, 40), ("alto", 21, 35)])
>>> pictures.toolTip().splitlines()
['Bass: F1 to A5', 'Alto: C3 to C5']
RangePictures.paintEvent
def paintEvent(_: QPaintEvent) -> None
Draw a staff for each clef with its lowest and highest note.
Parameters
_(QPaintEvent): The paint request; the whole widget is always redrawn.
Examples
>>> RangePictures([("treble", 22, 52), ("bass", 10, 40)]).grab().isNull()
False
NamePicture
NamePicture(
naming: str = 'letters',
*,
scale: float = 1.0,
parent: QWidget | None = None,
)
Bases: _Picture
How notes are named: C, D and E on a staff, labelled with letters or with solfège syllables.
Attributes
H, W(float): The picture’s height and width.LETTERS, SYLLABLES(tuple of str): The two sets of labels.naming(str): “letters” or “solfege”.
Examples
>>> NamePicture("solfege").toolTip()
'Solfège (Do Re Mi)'
Constructor
Create the picture.
Parameters
naming(str, default “letters”): “letters” or “solfege”.scale(float, default 1.0): How much to enlarge it. Keyword-only.parent(QWidget or None, default None): The widget that owns it. Keyword-only.
Constructor examples
>>> NamePicture().naming
'letters'
NamePicture.set_naming
def set_naming(naming: str) -> None
Choose which labels are drawn.
Parameters
naming(str): “letters” for C D E, or “solfege” for Do Re Mi.
Examples
>>> picture = NamePicture()
>>> picture.set_naming("solfege")
>>> picture.toolTip()
'Solfège (Do Re Mi)'
NamePicture.icon
@classmethod
def icon(
naming: str,
*,
scale: float = 1.6,
) -> QIcon
Return the picture as an icon.
Parameters
naming(str): “letters” or “solfege”.scale(float, default 1.6): How much to enlarge it. Keyword-only.
Returns
- QIcon: The icon.
Examples
>>> NamePicture.icon("letters").isNull()
False
NamePicture.paintEvent
def paintEvent(_: QPaintEvent) -> None
Draw the staff, the clef, the three notes and their labels.
Parameters
_(QPaintEvent): The paint request; the whole widget is always redrawn.
Examples
>>> NamePicture("letters").grab().isNull()
False