Alto
latest

alto.ui.keyboard

The on-screen piano keyboard, drawn to real proportions, and a miniature of the whole piano for choosing a span of keys.

KeyboardWidget shows a range of keys and can highlight one. KeyboardSpan shows all 88 keys in miniature, shades the range that will be asked, and can be dragged to change it. Colours and materials come from keyboard_styles.

Examples

>>> keyboard = KeyboardWidget()
>>> keyboard.show_key(60)
>>> keyboard.highlight
60

KeyboardWidget

KeyboardWidget(parent: QWidget | None = None)

Bases: QWidget

A piano keyboard drawn to real proportions that can highlight one key.

Attributes

  • lo (int): The lowest key shown, as a MIDI number.
  • hi (int): The highest key shown, as a MIDI number.
  • highlight (int or None): The key to highlight.
  • style_override (KeyboardStyle or None): A fixed style, for the preview cards in the settings; otherwise the style chosen in the settings is used.
  • pad (float): The frame padding, in pixels.
  • max_key_width (float): The widest a key may be, in pixels. Smaller when something else (the key signature) shares the page.
  • highlight_color (QColor): The colour of the highlighted key.

Examples

>>> keyboard = KeyboardWidget()
>>> (keyboard.lo, keyboard.hi)  # C3 to C5, until another range is shown
(48, 72)

Constructor

Create a keyboard showing the default range, with no key highlighted.

Parameters

  • parent (QWidget or None, default None): The widget that owns the keyboard.

Constructor examples

>>> KeyboardWidget().highlight is None
True

KeyboardWidget.style

@property
def style() -> KeyboardStyle

Return the style the keyboard is drawn in.

Returns

  • KeyboardStyle: The fixed style if one is set, otherwise the style chosen in the settings.

Examples

>>> keyboard = KeyboardWidget()
>>> keyboard.style_override = keyboard_styles.BY_KEY["modern"]
>>> keyboard.style.label
'Modern piano'

KeyboardWidget.refit

def refit() -> None

Size and redraw the keyboard after the style changes.

Some styles have a taller strip above the keys.

Examples

>>> keyboard = KeyboardWidget()
>>> keyboard.refit()
>>> keyboard.height() > 0
True

KeyboardWidget.resizeEvent

def resizeEvent(event: QResizeEvent) -> None

Change the height to match the new width, since keys are drawn to real proportions.

Parameters

  • event (QResizeEvent): The resize that happened.

Examples

>>> keyboard = KeyboardWidget()
>>> keyboard.show()
>>> keyboard.resize(300, 300)
>>> keyboard.height()  # narrower, so shorter
143

KeyboardWidget.show_key

def show_key(
    midi: int | None,
    *,
    span: tuple[int, int] | None = None,
) -> None

Highlight a key, and optionally choose the range of keys to show.

Parameters

  • midi (int or None): The key to highlight, or None for no highlight.
  • span (tuple of (int, int) or None, default None): The lowest and highest key to show; it is widened to whole white keys. Keyword-only.

Examples

>>> keyboard = KeyboardWidget()
>>> keyboard.show_key(60, span=(49, 71))  # C#3 is widened to C3
>>> (keyboard.lo, keyboard.hi, keyboard.highlight)
(48, 71, 60)

KeyboardWidget.set_highlight_color

def set_highlight_color(color: QColor) -> None

Choose the colour of the highlighted key and redraw.

Parameters

  • color (QColor): The colour.

Examples

>>> keyboard = KeyboardWidget()
>>> keyboard.set_highlight_color(QColor("#2e7d32"))
>>> keyboard.highlight_color.name()
'#2e7d32'

KeyboardWidget.paintEvent

def paintEvent(_: QPaintEvent) -> None

Draw the case, the keys, the highlighted key and the style’s extras.

Parameters

  • _ (QPaintEvent): The paint request; the whole widget is always redrawn.

Examples

>>> keyboard = KeyboardWidget()
>>> keyboard.show_key(60)
>>> keyboard.grab().isNull()
False

KeyboardSpan

KeyboardSpan(
    parent: QWidget | None = None,
    *,
    compact: bool = False,
    size: tuple[int, int] = (124, 26),
)

Bases: QWidget

The whole 88-key piano in miniature, with the keys that will be asked shaded.

The full-size one can be dragged across to choose the span: dragged is emitted with the lowest and highest key as it changes.

Attributes

  • dragged (Signal): Emitted with the lowest and highest key (MIDI numbers) as the span is dragged.
  • lo (int): The lowest key shaded.
  • hi (int): The highest key shaded.

Examples

>>> span = KeyboardSpan()
>>> span.set_span(60, hi=72)
>>> (span.lo, span.hi)
(60, 72)

Constructor

Create the miniature, shading the default range.

Parameters

  • parent (QWidget or None, default None): The widget that owns it.
  • compact (bool, default False): Make a fixed-size version that ignores the mouse, for a summary in a menu row. Keyword-only.
  • size (tuple of (int, int), default (124, 26)): The width and height of the compact version, in pixels. Keyword-only.

Constructor examples

>>> KeyboardSpan(compact=True, size=(100, 20)).size().width()
100

KeyboardSpan.key_at

def key_at(pos: QPointF) -> int

Return the key under a point.

Parameters

  • pos (QPointF): The position in the widget.

Returns

  • int: The MIDI number: a black key where one is drawn there, else the white key (clamped to the ends of the piano).

Examples

>>> span = KeyboardSpan()
>>> span.resize(500, 64)
>>> span.key_at(QPointF(0, 50)), span.key_at(QPointF(499, 50))  # the lowest and highest keys
(21, 108)
>>> span.key_at(QPointF(250, 50))
64

KeyboardSpan.mousePressEvent

def mousePressEvent(event: QMouseEvent) -> None

Start choosing a span: grab an edge, pick the span up, or start a new one.

Parameters

  • event (QMouseEvent): The press. Only the left button does anything.

Examples

>>> from PySide6.QtCore import QEvent
>>> span = KeyboardSpan()
>>> span.resize(500, 64)
>>> got = []
>>> _ = span.dragged.connect(lambda lo, hi: got.append((lo, hi)))
>>> point = QPointF(5, 50)
>>> span.mousePressEvent(QMouseEvent(QEvent.Type.MouseButtonPress, point, point, Qt.MouseButton.LeftButton,
...                                  Qt.MouseButton.LeftButton, Qt.KeyboardModifier.NoModifier))
>>> got  # a press outside the span starts a new one on that key
[(21, 21)]

KeyboardSpan.mouseMoveEvent

def mouseMoveEvent(event: QMouseEvent) -> None

Drag the span, or (with no button held) show the cursor for what a press here would do.

Parameters

  • event (QMouseEvent): The move.

Examples

>>> from PySide6.QtCore import QEvent
>>> span = KeyboardSpan()
>>> span.resize(500, 64)
>>> middle = QPointF(sum(span._edges()) / 2, 50)
>>> span.mouseMoveEvent(QMouseEvent(QEvent.Type.MouseMove, middle, middle, Qt.MouseButton.NoButton,
...                                 Qt.MouseButton.NoButton, Qt.KeyboardModifier.NoModifier))
>>> span.cursor().shape() == Qt.CursorShape.OpenHandCursor  # inside the span: it can be picked up
True

KeyboardSpan.mouseReleaseEvent

def mouseReleaseEvent(event: QMouseEvent) -> None

Finish a drag and refresh the cursor for where the pointer now is.

Parameters

  • event (QMouseEvent): The release.

Examples

>>> from PySide6.QtCore import QEvent
>>> span = KeyboardSpan()
>>> span.resize(500, 64)
>>> point = QPointF(5, 50)
>>> span.mouseReleaseEvent(QMouseEvent(QEvent.Type.MouseButtonRelease, point, point, Qt.MouseButton.LeftButton,
...                                    Qt.MouseButton.NoButton, Qt.KeyboardModifier.NoModifier))
>>> span._mode is None
True

KeyboardSpan.set_span

def set_span(
    lo: int,
    *,
    hi: int,
) -> None

Choose which keys are shaded and redraw.

Parameters

  • lo (int): The lowest key asked, as a MIDI number.
  • hi (int): The highest key asked. Keyword-only.

Examples

>>> span = KeyboardSpan()
>>> span.set_span(48, hi=72)
>>> (span.lo, span.hi)
(48, 72)

KeyboardSpan.paintEvent

def paintEvent(_: QPaintEvent) -> None

Draw the whole piano in miniature with the asked keys shaded and the span’s edges marked.

Parameters

  • _ (QPaintEvent): The paint request; the whole widget is always redrawn.

Examples

>>> span = KeyboardSpan()
>>> span.grab().isNull()
False