dymokomi/luce-ui
Source of release 0.19.6
## Application intent shared by toolbars, menus and window shortcuts. A command
## knows nothing about files or editors; the connected callback supplies behavior.
## An optional id lets a registry find and invoke a command by name, so shortcuts,
## scripts and other tools can drive the same commands the UI does.
from luce_window import input
import platform
import interop
import ownership
import memory
import result
## A key chord: `key` with or without the primary modifier (Command or Control;
## either one matches), Shift and Alt, compared exactly. An unknown key binds
## nothing.
pub struct Shortcut:
pub let key: input.Key = input.Key.unknown
pub let primary: bool = false
pub let shift: bool = false
pub let alt: bool = false
func matches(event: input.Event) -> bool:
return self.key != input.Key.unknown and event.kind == input.EventKind.key_down and event.key == self.key and (event.modifiers.control or event.modifiers.super) == self.primary and event.modifiers.shift == self.shift and event.modifiers.alt == self.alt
## Parse a chord like "cmd+shift+s", "f5" or "cmd+alt+[" into a shortcut. The
## `+`-separated tokens are case-insensitive: `cmd`/`ctrl`/`super` map to the
## primary modifier, plus `shift` and `alt`; the final token names the key.
## An empty chord (or "none") is unbound.
pub static func parse(text: str) -> Shortcut!:
var primary = false
var shift = false
var alt = false
var key = input.Key.unknown
var start: usize = 0
for index in 0..<text.length + 1:
if index == text.length or text.bytes[index] == 43:
if index > start:
let token = (str)text.bytes[start..<index]
if fold_equal(token, "cmd") or fold_equal(token, "ctrl") or fold_equal(token, "control") or fold_equal(token, "super") or fold_equal(token, "meta") or fold_equal(token, "primary"):
primary = true
elif fold_equal(token, "shift"):
shift = true
elif fold_equal(token, "alt") or fold_equal(token, "option") or fold_equal(token, "opt"):
alt = true
elif not (fold_equal(token, "none") or fold_equal(token, "unbound")):
key = key_from_name(token)
start = index + 1
if key == input.Key.unknown and not (fold_equal(text, "") or fold_equal(text, "none") or fold_equal(text, "unbound")):
error(result.invalid, "a shortcut chord names an unknown key")
return Shortcut(key = key, primary = primary, shift = shift, alt = alt)
## Whether the shortcut binds a key at all.
pub func is_bound() -> bool:
return self.key != input.Key.unknown
## The chord as a menu shows it ("⌘⇧S" on macOS, "Ctrl+Shift+S" elsewhere),
## or "" when unbound.
pub func text() -> interop.Owned[str]!:
var buffer: u8[32]
let length = write_chord(self, buffer)
return try interop.copy_text((str)buffer[..<length])
## The chord as a settings file stores it and `parse` reads it back:
## "cmd+shift+s", "f5", "alt+[", or "none" when unbound.
pub func chord() -> interop.Owned[str]!:
var buffer: u8[48]
let length = write_storable(self, buffer)
return try interop.copy_text((str)buffer[..<length])
## A named action: its caption, shortcut, optional registry id, icon, enabled
## state and the callbacks that triggering it runs. A command with `items` is a
## submenu's title: a menu opens those commands beside it instead of running it.
pub struct Command:
let name: interop.Owned[str]
var caption: interop.Owned[str]
var glyph: interop.Owned[str]
let triggered: interop.Signal[unit]
var children: Commands
var binding: Shortcut
var enabled: bool
var divider: bool
var checked: bool
## `divider` makes a non-selectable separator that groups the items around it in a
## menu: it carries no caption or action, draws as a line, and is skipped for
## selection and search. Build one with `Command("", divider = true)`. `icon`
## names a luciaos-assets icon a menu draws before the caption.
pub func init(text: str, shortcut: Shortcut = Shortcut(), id: str = "", divider: bool = false, icon: str = "") -> !:
let name = try interop.copy_text(id)
errdefer name.release()
let caption = try interop.copy_text(text)
errdefer caption.release()
let glyph = try interop.copy_text(icon)
errdefer glyph.release()
let triggered = try interop.Signal[unit]()
self.name = name
self.caption = caption
self.glyph = glyph
self.triggered = triggered
self.children = Commands()
self.binding = shortcut
self.enabled = not divider
self.divider = divider
self.checked = false
pub func is_divider() -> bool:
return self.divider
## The registry name, empty for an anonymous command.
pub func id() -> str:
return self.name.value
pub func text() -> interop.Owned[str]:
return self.caption.clone()
## Relabel a live command, for one whose caption reflects its state.
pub func set_text(text: str) -> !:
let replacement = try interop.copy_text(text)
let previous_caption = self.caption
self.caption = replacement
previous_caption.release()
## The icon's name, empty for none.
pub func icon() -> str:
return self.glyph.value
pub func set_icon(icon: str) -> !:
let replacement = try interop.copy_text(icon)
let previous = self.glyph
self.glyph = replacement
previous.release()
## The submenu's commands; empty for an ordinary command.
pub func items() -> const interop.Reference[Command][]:
return self.children.values()
pub func has_items() -> bool:
return self.children.values().length > 0
## How many commands the submenu has, and the one at `index` (for Luce,
## which reads them one by one).
pub func item_count() -> i64:
return (i64)self.children.values().length
pub func item(index: i64) -> interop.Reference[Command]!:
if index < 0 or (usize)index >= self.children.values().length:
error(result.invalid, "item index is outside this submenu")
return self.children.values()[(usize)index].clone()
## Make this command a submenu of `items` (none: an ordinary command again).
pub func set_items(items: const interop.Reference[Command][]) -> !:
try self.children.set(items)
pub func shortcut() -> Shortcut:
return self.binding
## Rebind this command, for a keymap loaded from settings.
pub func set_shortcut(shortcut: Shortcut):
self.binding = shortcut
## Write a display label for the shortcut into `buffer` (macOS modifier glyphs then
## the key), returning the byte count; zero when the command has no binding.
pub func write_shortcut(buffer: u8[]) -> usize:
return write_chord(self.binding, buffer)
pub func is_enabled() -> bool:
return self.enabled
## A command that is a setting on or off: a menu draws a tick after it when on.
pub func is_checked() -> bool:
return self.checked
pub func set_checked(checked: bool):
self.checked = checked
## A disabled command ignores `trigger`, and its shortcut no longer takes the key:
## the press goes on to the next matching command or to the focused widget, as a
## disabled menu item's key equivalent does on macOS.
pub func set_enabled(enabled: bool):
self.enabled = enabled
pub func on_trigger(callback: interop.Callback[unit, unit]) -> interop.Reference[interop.Connection]!:
return try self.triggered.connect(callback)
## Run the connected callbacks; nothing while disabled.
pub func trigger() -> interop.Outcome[unit]:
return self.triggered.emit(()) if self.enabled else result.success[unit](())
pub func close():
self.children.close()
self.triggered.close()
self.triggered.release()
self.glyph.release()
self.caption.release()
self.name.release()
func trace(visit: func(ownership.Object*, void*) -> unit, context: void*):
self.name.trace(visit, context)
self.caption.trace(visit, context)
self.glyph.trace(visit, context)
self.triggered.trace(visit, context)
self.children.trace(visit, context)
pub let command_type: interop.Type[Command] = interop.Type[Command]("Command", Command.close, Command.trace, closeable = true, main_thread = true)
## An owning command registry used by applications and menus. Replacement is
## atomic and callbacks retain their selected command across reentrant changes.
## `find` resolves a command by id so a keymap or script can invoke it.
pub struct Commands:
var items: interop.Reference[Command][]
pub func init():
var empty: interop.Reference[Command][]
self.items = empty
pub func values() -> const interop.Reference[Command][]:
return self.items
## The command with this id, or none. An empty id never matches.
pub func find(id: str) -> interop.Reference[Command]?:
if id == "":
return none
for item in self.items:
if item.value().id() == id:
return item.clone()
return none
## Replace the registry with `items`, at most 4096, retaining each.
pub func set(items: const interop.Reference[Command][]) -> !:
if items.length > 4096:
error(result.invalid, "a command registry supports at most 4096 entries")
for item in items:
_ = try item.get()
var copied: interop.Reference[Command][]
if items.length > 0:
copied = try new interop.Reference[Command][items.length] --- in memory.heap
for index in 0..<items.length:
copied[index] = items[index].clone()
# The new list in place before the old one is released: a release can
# run the cycle collector, which traces `items`.
let previous = self.items
self.items = copied
release_commands(previous)
## Match a key press against the shortcuts of enabled commands in registry order.
## The first match consumes the event and triggers its command (a key repeat is
## consumed without triggering again). A disabled command's shortcut is skipped,
## so the key goes to the next match or on to the focused widget. Returns whether
## a shortcut consumed the press.
pub func dispatch(event: input.Event) -> interop.Outcome[bool]:
for item in self.items:
if item.value().is_enabled() and item.value().shortcut().matches(event):
let selected = item.clone()
defer selected.release()
if not event.repeated:
let invoked = selected.value().trigger()
defer invoked.release()
_ = invoked.get() catch failure:
return result.failure[bool](failure.code, failure.message)
return result.success[bool](true)
return result.success[bool](false)
pub func close():
let previous = self.items
var empty: interop.Reference[Command][]
self.items = empty
release_commands(previous)
pub func trace(visit: func(ownership.Object*, void*) -> unit, context: void*):
for item in self.items:
item.trace(visit, context)
func release_commands(items: interop.Reference[Command][]):
for item in items:
item.release()
if items.length > 0:
free(items) in memory.heap
## macOS modifier glyphs (⌥⇧⌘) then the key. Key names stay ASCII so the label reads
## correctly even when the UI font lacks the fancier dedicated key glyphs.
func write_chord(shortcut: Shortcut, buffer: u8[]) -> usize:
if shortcut.key == input.Key.unknown:
return 0
var pos: usize = 0
if not platform.macos:
# Windows and Linux spell modifiers out, and their UI fonts lack the Mac glyphs.
if shortcut.primary:
pos = put_bytes(buffer, pos, b"Ctrl+")
if shortcut.shift:
pos = put_bytes(buffer, pos, b"Shift+")
if shortcut.alt:
pos = put_bytes(buffer, pos, b"Alt+")
return write_key(shortcut.key, buffer, pos)
if shortcut.alt:
pos = put_bytes(buffer, pos, b"\xe2\x8c\xa5")
if shortcut.shift:
pos = put_bytes(buffer, pos, b"\xe2\x87\xa7")
if shortcut.primary:
pos = put_bytes(buffer, pos, b"\xe2\x8c\x98")
return write_key(shortcut.key, buffer, pos)
## The storable, parseable form of a chord: lowercase tokens joined by `+`.
func write_storable(shortcut: Shortcut, buffer: u8[]) -> usize:
if shortcut.key == input.Key.unknown:
return put_bytes(buffer, 0, b"none")
var pos: usize = 0
if shortcut.primary:
pos = put_bytes(buffer, pos, b"cmd+")
if shortcut.shift:
pos = put_bytes(buffer, pos, b"shift+")
if shortcut.alt:
pos = put_bytes(buffer, pos, b"alt+")
let code = (u16)shortcut.key
if code >= (u16)input.Key.a and code <= (u16)input.Key.z:
let letter: u8[1] = [(u8)((u16)'a' + code - (u16)input.Key.a)]
return put_bytes(buffer, pos, letter)
if shortcut.key == input.Key.digit_0:
return put_bytes(buffer, pos, b"0")
if code >= (u16)input.Key.digit_1 and code <= (u16)input.Key.digit_9:
let digit: u8[1] = [(u8)((u16)'1' + code - (u16)input.Key.digit_1)]
return put_bytes(buffer, pos, digit)
if code >= (u16)input.Key.f1 and code <= (u16)input.Key.f12:
var p = put_bytes(buffer, pos, b"f")
let number = code - (u16)input.Key.f1 + 1
if number >= 10:
let tens: u8[1] = [(u8)((u16)'0' + number // 10)]
p = put_bytes(buffer, p, tens)
let ones: u8[1] = [(u8)((u16)'0' + number % 10)]
return put_bytes(buffer, p, ones)
return put_bytes(buffer, pos, storable_word(shortcut.key))
## The name `parse` accepts for a named or symbol key.
func storable_word(key: input.Key) -> const u8[]:
if key == input.Key.enter: return b"enter"
if key == input.Key.escape: return b"escape"
if key == input.Key.tab: return b"tab"
if key == input.Key.space: return b"space"
if key == input.Key.backspace: return b"backspace"
if key == input.Key.delete: return b"delete"
if key == input.Key.left: return b"left"
if key == input.Key.right: return b"right"
if key == input.Key.up: return b"up"
if key == input.Key.down: return b"down"
if key == input.Key.home: return b"home"
if key == input.Key.end: return b"end"
if key == input.Key.page_up: return b"page_up"
if key == input.Key.page_down: return b"page_down"
return key_word(key)
func put_bytes(buffer: u8[], pos: usize, bytes: const u8[]) -> usize:
var p = pos
for index in 0..<bytes.length:
if p < buffer.length:
buffer[p] = bytes[index]
p += 1
return p
func write_key(key: input.Key, buffer: u8[], pos: usize) -> usize:
let code = (u16)key
if code >= (u16)input.Key.a and code <= (u16)input.Key.z:
let letter: u8[1] = [(u8)((u16)'A' + code - (u16)input.Key.a)]
return put_bytes(buffer, pos, letter)
if key == input.Key.digit_0:
return put_bytes(buffer, pos, b"0")
if code >= (u16)input.Key.digit_1 and code <= (u16)input.Key.digit_9:
let digit: u8[1] = [(u8)((u16)'1' + code - (u16)input.Key.digit_1)]
return put_bytes(buffer, pos, digit)
if code >= (u16)input.Key.f1 and code <= (u16)input.Key.f12:
var p = put_bytes(buffer, pos, b"F")
let number = code - (u16)input.Key.f1 + 1
if number >= 10:
let tens: u8[1] = [(u8)((u16)'0' + number // 10)]
p = put_bytes(buffer, p, tens)
let ones: u8[1] = [(u8)((u16)'0' + number % 10)]
return put_bytes(buffer, p, ones)
return put_bytes(buffer, pos, key_word(key))
func key_word(key: input.Key) -> const u8[]:
if key == input.Key.enter: return b"Enter"
if key == input.Key.escape: return b"Esc"
if key == input.Key.tab: return b"Tab"
if key == input.Key.space: return b"Space"
if key == input.Key.backspace or key == input.Key.delete: return b"Del"
if key == input.Key.left: return b"Left"
if key == input.Key.right: return b"Right"
if key == input.Key.up: return b"Up"
if key == input.Key.down: return b"Down"
if key == input.Key.home: return b"Home"
if key == input.Key.end: return b"End"
if key == input.Key.page_up: return b"PgUp"
if key == input.Key.page_down: return b"PgDn"
if key == input.Key.left_bracket: return b"["
if key == input.Key.right_bracket: return b"]"
if key == input.Key.minus: return b"-"
if key == input.Key.equal: return b"="
if key == input.Key.comma: return b","
if key == input.Key.period: return b"."
if key == input.Key.slash: return b"/"
if key == input.Key.semicolon: return b";"
if key == input.Key.apostrophe: return b"'"
if key == input.Key.grave: return b"`"
if key == input.Key.backslash: return b"\\"
return b"?"
## Case-insensitive ASCII compare of a chord token against a lowercase literal.
func fold_equal(text: str, lower: str) -> bool:
if text.length != lower.length:
return false
for index in 0..<text.length:
var byte = text.bytes[index]
if byte >= 65 and byte <= 90:
byte += 32
if byte != lower.bytes[index]:
return false
return true
## Map a key name to a physical key: a letter, a digit, a punctuation symbol, a
## function key `f1`..`f12`, or a named editing key. Unknown names are rejected.
func key_from_name(name: str) -> input.Key:
if name.length == 1:
var byte = name.bytes[0]
if byte >= 65 and byte <= 90:
byte += 32
if byte >= 97 and byte <= 122:
return (input.Key)((u16)input.Key.a + (u16)byte - 97)
if byte >= 49 and byte <= 57:
return (input.Key)((u16)input.Key.digit_1 + (u16)byte - 49)
if byte == 48: return input.Key.digit_0
if byte == 91: return input.Key.left_bracket
if byte == 93: return input.Key.right_bracket
if byte == 45: return input.Key.minus
if byte == 61: return input.Key.equal
if byte == 44: return input.Key.comma
if byte == 46: return input.Key.period
if byte == 47: return input.Key.slash
if byte == 59: return input.Key.semicolon
if byte == 39: return input.Key.apostrophe
if byte == 96: return input.Key.grave
if byte == 92: return input.Key.backslash
return input.Key.unknown
if fold_equal(name, "enter") or fold_equal(name, "return"): return input.Key.enter
if fold_equal(name, "escape") or fold_equal(name, "esc"): return input.Key.escape
if fold_equal(name, "tab"): return input.Key.tab
if fold_equal(name, "space"): return input.Key.space
if fold_equal(name, "backspace"): return input.Key.backspace
if fold_equal(name, "delete") or fold_equal(name, "del"): return input.Key.delete
if fold_equal(name, "left"): return input.Key.left
if fold_equal(name, "right"): return input.Key.right
if fold_equal(name, "up"): return input.Key.up
if fold_equal(name, "down"): return input.Key.down
if fold_equal(name, "home"): return input.Key.home
if fold_equal(name, "end"): return input.Key.end
if fold_equal(name, "page_up") or fold_equal(name, "pageup"): return input.Key.page_up
if fold_equal(name, "page_down") or fold_equal(name, "pagedown"): return input.Key.page_down
if name.length >= 2 and (name.bytes[0] == 102 or name.bytes[0] == 70):
var number: u16 = 0
for index in 1..<name.length:
let digit = name.bytes[index]
if digit < 48 or digit > 57:
return input.Key.unknown
number = number * 10 + (u16)digit - 48
if number >= 1 and number <= 12:
return (input.Key)((u16)input.Key.f1 + number - 1)
return input.Key.unknown
test "Shortcut.parse reads modifiers, letters, digits, symbols and function keys":
let save = try Shortcut.parse("cmd+s")
assert(save.key == input.Key.s and save.primary and not save.shift and not save.alt)
let all_mods = try Shortcut.parse("Cmd+Shift+Alt+[")
assert(all_mods.key == input.Key.left_bracket and all_mods.primary and all_mods.shift and all_mods.alt)
assert((try Shortcut.parse("f5")).key == input.Key.f5)
assert((try Shortcut.parse("shift+f12")).key == input.Key.f12)
assert((try Shortcut.parse("cmd+1")).key == input.Key.digit_1)
assert((try Shortcut.parse("none")).key == input.Key.unknown)
var rejected = false
_ = Shortcut.parse("cmd+nope") catch failure:
rejected = true
recover Shortcut()
assert(rejected)
test "a shortcut round-trips through its storable chord":
for chord in ["cmd+shift+s", "f5", "alt+[", "cmd+alt+left", "shift+f12", "none", "cmd+0", "cmd+,", "page_down"]:
let parsed = try Shortcut.parse(chord)
let stored = try parsed.chord()
defer stored.release()
assert(stored.value == chord)
let shown = try (try Shortcut.parse("cmd+shift+s")).text()
defer shown.release()
# the menu label is the platform's: Mac glyphs, else the modifiers spelled out
assert(shown.value == ("⇧⌘S" if platform.macos else "Ctrl+Shift+S"))
assert(not Shortcut().is_bound() and (try Shortcut.parse("b")).is_bound())