Alto
latest

alto.ui.keyboard_styles

Keyboard styles: the colours and materials the on-screen piano keys are drawn in.

There are ready-made styles (STYLES) and a custom one built from colours chosen part by part.

Examples

>>> BY_KEY["classic"].label
'Classic'
>>> style_for("no such style").key == DEFAULT
True

KeyboardStyle

KeyboardStyle(
    key: str,
    *,
    label: str,
    note: str,
    white: tuple[str, str],
    white_edge: str,
    black: tuple[str, str],
    black_edge: str,
    case: str | None = DEFAULT_CASE,
    felt: str | None = None,
    cap: str | None = None,
    narrow: float = 1.0,
    gap: float = 1.0,
    rail: float = 8.0,
    thick: bool = False,
    hue: bool = False,
    glow: bool = False,
    ink: bool = False,
    knobs: bool = False,
    reverse_below: int | None = None,
    dot: str | None = None,
    round: float = 7.0,
)

How a keyboard looks: the colours of the keys and the case, and a few details of the drawing.

Attributes

  • key (str): The identifier saved in the settings.
  • label (str): The name shown in the interface. Keyword-only.
  • note (str): A few words on what it is modelled on. Keyword-only.
  • white (tuple of (str, str)): The natural keys’ colour at the top and at the bottom. Keyword-only.
  • white_edge (str): The outline colour of the natural keys. Keyword-only.
  • black (tuple of (str, str)): The sharps’ colour at the top and at the bottom. Keyword-only.
  • black_edge (str): The outline colour of the sharps. Keyword-only.
  • case (str or None): The body around the keys; None draws no body. Keyword-only.
  • felt (str or None): A strip of felt under the fallboard. Keyword-only.
  • cap (str or None): A bone cap on top of each sharp. Keyword-only.
  • narrow (float, default 1.0): How wide the sharps are, compared with a piano’s. Keyword-only.
  • gap (float, default 1.0): Pixels between neighbouring naturals. Keyword-only.
  • rail (float, default 8.0): The height of the strip above the keys. Keyword-only.
  • thick (bool, default False): Heavy outlines. Keyword-only.
  • hue (bool, default False): Colour each key by its note name. Keyword-only.
  • glow (bool, default False): A soft halo around the outlines. Keyword-only.
  • ink (bool, default False): Hatched sharps, like an engraving. Keyword-only.
  • knobs (bool, default False): A row of organ stop knobs in the strip above the keys. Keyword-only.
  • reverse_below (int or None): Keys under this MIDI number swap colours (an organ’s preset keys). Keyword-only.
  • dot (str or None): The colour of a dot that marks every C. Keyword-only.
  • round (float, default 7.0): The most the lower corners of a natural are rounded, in pixels. Keyword-only.

Examples

>>> style = BY_KEY["modern"]
>>> style.label, style.case
('Modern piano', '#0d0d0f')

custom_colours

def custom_colours() -> dict[str, str | None]

Return the colour of each part of the custom keyboard.

Returns

  • dict of str to str or None: Part name (“naturals”, “sharps”, “case”, “felt” or “caps”) to its colour, or None where an optional part is left out.

Examples

>>> sorted(custom_colours())
['caps', 'case', 'felt', 'naturals', 'sharps']

custom_style

def custom_style() -> KeyboardStyle

Build the style from the custom colours.

Gradients and outlines are worked out from each part’s colour.

Returns

  • KeyboardStyle: The custom style, with the key “custom”.

Examples

>>> custom_style().key, custom_style().label
('custom', 'Custom')

style_for

def style_for(key: str) -> KeyboardStyle

Return the style with a given key.

Parameters

  • key (str): A key of BY_KEY, or “custom”.

Returns

  • KeyboardStyle: That style; the default (Classic) if the key is not known.

Examples

>>> style_for("modern").label
'Modern piano'
>>> style_for("nonsense").label
'Classic'

current

def current() -> KeyboardStyle

Return the keyboard style in use.

Returns

  • KeyboardStyle: The style chosen in the settings (Classic until another is chosen).

Examples

>>> current().key in BY_KEY or current().key == CUSTOM
True

load_style

def load_style() -> None

Apply the saved style (Classic if none is saved or it is unknown), and the saved custom colours.

Examples

>>> store().setValue("ui/keyboard", "modern")
>>> load_style()
>>> current().key
'modern'
>>> set_style(DEFAULT)

set_style

def set_style(key: str) -> None

Choose and save a style, and redraw every keyboard already on screen.

Parameters

  • key (str): A key of BY_KEY, or “custom”.

Examples

>>> set_style("modern")
>>> current().label
'Modern piano'
>>> set_style(DEFAULT)

set_custom_colour

def set_custom_colour(
    part: str,
    *,
    colour: str | None,
) -> None

Colour one part of the custom keyboard and switch to the custom style.

Parameters

  • part (str): One of “naturals”, “sharps”, “case”, “felt” or “caps”.
  • colour (str or None): A colour such as ‘#336699’, or None to leave an optional part (case, felt or caps) out. Keyword-only.

Examples

>>> set_custom_colour("naturals", colour="#ffffff")
>>> current().key, custom_colours()["naturals"]
('custom', '#ffffff')
>>> set_custom_colour("naturals", colour=DEFAULT_CUSTOM["naturals"])
>>> set_style(DEFAULT)

on_redraw

def on_redraw(hook: Callable[[], None]) -> None

Register a function to call whenever the keyboard style changes.

The keyboard widgets live in a module that imports this one, so they register themselves here instead of being found by this module.

Parameters

  • hook (Callable): A function with no arguments that lays out and repaints what depends on the style.

Examples

>>> calls = []
>>> def repaint() -> None:
...     calls.append(1)
>>> on_redraw(repaint)
>>> _redraw()
>>> calls
[1]
>>> _redraw_hooks.remove(repaint)

reversed_key

def reversed_key(
    style: KeyboardStyle,
    *,
    midi: int,
) -> bool

Report whether a key has swapped colours, as the low preset keys of an organ do.

Parameters

  • style (KeyboardStyle): The style.
  • midi (int): The key’s MIDI number. Keyword-only.

Returns

  • bool: True if the style swaps colours below some key and this key is below it.

Examples

>>> from dataclasses import replace
>>> reversed_key(BY_KEY["classic"], midi=40)
False
>>> reversed_key(replace(BY_KEY["classic"], reverse_below=50), midi=40)
True

key_brush

def key_brush(
    style: KeyboardStyle,
    *,
    midi: int,
    black: bool,
    y: float,
    height: float,
) -> QBrush

Return the fill for a key.

Parameters

  • style (KeyboardStyle): The style.
  • midi (int): The key’s MIDI number. Keyword-only.
  • black (bool): True for a sharp or flat, False for a natural. Keyword-only.
  • y (float): The key’s top edge, in pixels. Keyword-only.
  • height (float): The key’s height, in pixels. Keyword-only.

Returns

  • QBrush: A solid colour, a top-to-bottom gradient, or (for styles that colour keys by note) a colour that depends on the note.

Examples

>>> key_brush(BY_KEY["classic"], midi=60, black=False, y=0, height=100).color().name()
'#fbfbfc'
>>> key_brush(BY_KEY["modern"], midi=60, black=False, y=0, height=100).gradient() is not None
True

edge_color

def edge_color(
    style: KeyboardStyle,
    *,
    midi: int,
    black: bool,
) -> QColor

Return the outline colour for a key.

Parameters

  • style (KeyboardStyle): The style.
  • midi (int): The key’s MIDI number. Keyword-only.
  • black (bool): True for a sharp or flat, False for a natural. Keyword-only.

Returns

  • QColor: The outline colour.

Examples

>>> edge_color(BY_KEY["classic"], midi=60, black=False).name()
'#9a9a9f'
>>> edge_color(BY_KEY["classic"], midi=61, black=True).name()
'#111114'