Окна, виджеты и интерфейс VLTONE

Окно или закреплённая панель

ui.window принимает дерево контролов. Без dock окно плавающее; left/right/top/bottom создают панель QDockWidget с возможностью перетаскивания и отделения. В предпросмотре панель всегда плавает. Заголовок показывает закреплённый проект. Повторный запуск поднимает существующий инструмент. Закрытие последнего окна завершает обычную команду; для фонового режима нужен background=true в манифесте.

vlt.ui.window{id="tool", title="My tool", dock="right", children={
  {type="row", children={
    {type="field", id="name", label="Name", value="Intro"},
    {type="button", text="Read", onClick=function()
      local state = vlt.ui.get{id="name"}
      vlt.ui.set{id="status", text=state.value}
    end}
  }},
  {type="table", id="files", columns={"Name", "Size"}, rows={{"kick.wav", "2048"}}},
  {type="label", id="status", text="Ready"}
}}

Контролы и компоновка

Типы	Свойства
column, row, group	children, spacing, margin; у group текст заголовка text. У дочерних элементов stretch задаёт долю растяжения.
grid, scroll, splitter	grid.columns — 1…32, заполнение по строкам. scroll прокручивает children. splitter.orientation — horizontal/vertical, области меняются мышью.
tabs	children с title; value — номер вкладки с 1; onChange получает новый номер.
button, menu, toggle	text, onClick; у menu items={text,onClick}; у toggle value и onChange.
field, textEdit	value — строка, text — подсказка пустого поля, readOnly; field отправляет onChange после редактирования, textEdit — объединённые обновления текста.
list, choice	items — строки, value — индекс с 1 (0 — нет выбора), onChange. ui.set может заменить items.
table	columns — заголовки, rows — массив массивов строк. editable включает ввод. onClick: value={row,column}; onChange: value={row,column,text}. Индексы с 1. ui.get возвращает rows и выбранную строку value.
knob, number, slider	min/max/value/onChange или bind={track,device,parameter,identity}. number также step,decimals,unit. Привязанные контролы синхронизируются с DAW, один жест — один Undo.
canvas, waveform	drawing — фигуры либо массив пиков 0…1. См. события ниже.
image, label, progress	image.path — ресурс пакета или разрешённый путь (files.read); label.text — обычный текст; progress.value — 0…1.
separator, spacer	Линия horizontal/vertical; растягиваемое свободное место или фиксированный размер.

Общие поля: id, label, tooltip, enabled, visible. width/height фиксируют размер; minWidth/minHeight задают минимум. Все размеры — логические пиксели, масштаб ОС применяется Qt. В одном дереве до 512 элементов, вложенность до 16; у экземпляра до 16 окон. Таблица: до 32 столбцов, 1024 строк и 16384 ячеек. Используйте страницы для больших данных.

Состояние и перестроение

ui.get{id} читает состояние; ui.set{id,...} обновляет value/text/visible/enabled/tooltip, список items, таблицу rows/columns и drawing. Программное обновление не вызывает onChange. ui.focus{id} поднимает окно и переводит фокус. Идентификаторы уникальны внутри одного запуска; чужие окна недоступны.

ui.replace{id="tool",children=...} целиком проверяет новое дерево перед заменой. При ошибке старое дерево остаётся рабочим. Для обычного изменения значения используйте ui.set, чтобы сохранить фокус и ввод. Состояние старых контролов не переносится автоматически.

Собственное рисование и ввод

Фигуры drawing: line (x,y,x2,y2), rect/ellipse (x,y,w,h,fill), text (x,y,text); color — цвет, width — толщина пера. Без color используется цвет текста темы. onPointer/onWheel/onKey/onResize — функции Lua, получающие {id,value}.

Обработчик	value
onPointer	phase: down/move/up/doubleClick; x,y; нормализованные nx,ny; width,height; button,buttons,modifiers. Перемещения объединяются в пределах жеста, границы жестов сохраняются.
onWheel	x,y,dx,dy,modifiers; dy обычно ±120 на шаг колеса. Без обработчика событие остаётся прокрутке родителя.
onKey	Нажатие клавиши: key (Left, Right, A…), text, code, repeat, modifiers. В фокусе этот canvas принимает клавиши вместо компьютерной MIDI-клавиатуры.
onResize	width,height. Частые уведомления объединяются. Начальный размер можно прочитать ui.get после создания окна.

button/buttons/modifiers используют флаги Qt: кнопки 1 — левая, 2 — правая, 4 — средняя. Обработчик должен быстро завершаться: обновляйте только нужный контрол. Длительные вычисления разбивайте на задания или короткие шаги таймера.

Штатный интерфейс

local workspace = vlt.workspace.get()
vlt.workspace.open{view="mixer", visible=true}
vlt.workspace.select{tracks={trackId}, clips={{track=trackId,clip=clipId}}}
vlt.workspace.open{view="sample", track=trackId, clip=clipId}
-- Устройство: identity берётся из parameters.list
vlt.workspace.open{view="plugin",track=trackId,device=deviceId,identity=identity}

Виды: arrangement, mixer, inspector, browser, master, assistant, notebook, trackOverview, context, pianoRoll, pattern, sample, automation, plugin. Видимость можно менять у панелей; редакторы открываются по совместимому типу клипа. get возвращает active/project/panels/selection. Для неактивной вкладки panels пуст. open/select требуют активную вкладку исходного проекта и запрещены в предпросмотре. Выделение проверяется целиком перед изменением. Эти операции локального интерфейса доступны в совместном проекте и не меняют документ.

Остальные действия доступны через commands.list/run и API проекта/параметров. callable означает, что команда вообще разрешена скриптам; available — доступность QAction сейчас. Вызов дополнительно проверяет права, режим AI, совместную сессию и проект. Сырые QWidget, нажатия по координатам и внутренности интерфейсов сторонних плагинов не доступны; параметры плагинов управляются через интерфейс хоста.

Рабочий пример

Установите папку examples/interactive-workbench через упаковку CLI или откройте main.lua в Creator вместе с manifest.json. Пример содержит таблицу медиа проекта, навигацию VLTONE и интерактивную XY-область. Исходник · Манифест.