scripted: widgets can now declare their settings in a manifest so they show up in the GUI

Author: ItsLemmy

assets/scripts/bongocat.lua

@@ -22,6 +22,26 @@
 --   bc=idle, dc=left slap, ba=right slap, da=both slap
 --   ef=sleep, gh=blink
 
+-- Self-describing manifest: lets Noctalia list this widget in the Add-widget
+-- picker and render its settings in the GUI. Must be the first statement, ahead
+-- of the keyboard-reader spawn below, so manifest extraction stays side-effect free.
+barWidget.define({
+  label = "Bongo Cat",
+  icon = "cat",
+  description = "A cat that slaps your bar when you type or to the beat",
+  settings = {
+    { key = "input_device", type = "string", label = "Keyboard device",
+      description = "/dev/input/eventN — requires evtest and membership in the input group" },
+    { key = "audio_spectrum", type = "bool", label = "React to audio", default = false },
+    { key = "tappy_mode", type = "bool", label = "Tap to the beat", default = false,
+      visible_when = { key = "audio_spectrum", values = { "true" } } },
+    { key = "rave_mode", type = "bool", label = "Rave colors on beat", default = false,
+      visible_when = { key = "audio_spectrum", values = { "true" } } },
+    { key = "use_mpris_filter", type = "bool", label = "Only react while media plays", default = false,
+      visible_when = { key = "audio_spectrum", values = { "true" } } },
+  },
+})
+
 barWidget.setFont("fonts/bongocat.otf")
 barWidget.setText("bc")
 barWidget.setUpdateInterval(50)

assets/scripts/screen_recorder.lua

@@ -6,6 +6,59 @@
 --   Right click  — toggle replay buffer (if enabled), or save replay (if active)
 --   Middle click — save replay buffer
 
+-- Self-describing manifest: lets Noctalia list this widget in the Add-widget
+-- picker and render its settings in the GUI. Must be the first statement.
+barWidget.define({
+    label = "Screen Recorder",
+    icon = "video",
+    description = "Record the screen with gpu-screen-recorder",
+    settings = {
+        { key = "video_source", type = "string", label = "Video source", default = "portal",
+          description = "\"portal\", \"focused-monitor\", or a monitor/output name" },
+        { key = "directory", type = "string", label = "Output directory",
+          description = "Defaults to ~/Videos when empty" },
+        { key = "filename_pattern", type = "string", label = "Filename pattern",
+          default = "recording_%Y%m%d_%H%M%S", description = "os.date pattern, without extension" },
+        { key = "frame_rate", type = "int", label = "Frame rate", default = 60, min = 1, max = 240 },
+        { key = "video_codec", type = "select", label = "Video codec", default = "h264",
+          options = {
+              { value = "h264", label = "H.264" }, { value = "hevc", label = "HEVC" },
+              { value = "av1", label = "AV1" }, { value = "vp8", label = "VP8" }, { value = "vp9", label = "VP9" },
+          } },
+        { key = "quality", type = "select", label = "Quality", default = "very_high",
+          options = {
+              { value = "medium", label = "Medium" }, { value = "high", label = "High" },
+              { value = "very_high", label = "Very high" }, { value = "ultra", label = "Ultra" },
+          } },
+        { key = "resolution", type = "string", label = "Resolution", default = "original",
+          description = "\"original\" or WIDTHxHEIGHT, e.g. 1920x1080" },
+        { key = "audio_source", type = "select", label = "Audio source", default = "default_output",
+          options = {
+              { value = "default_output", label = "System output" },
+              { value = "default_input", label = "Microphone" },
+              { value = "both", label = "Output + microphone" },
+              { value = "none", label = "No audio" },
+          } },
+        { key = "audio_codec", type = "select", label = "Audio codec", default = "opus",
+          options = {
+              { value = "opus", label = "Opus" }, { value = "aac", label = "AAC" }, { value = "flac", label = "FLAC" },
+          } },
+        { key = "show_cursor", type = "bool", label = "Show cursor", default = true },
+        { key = "color_range", type = "select", label = "Color range", default = "limited",
+          options = { { value = "limited", label = "Limited" }, { value = "full", label = "Full" } } },
+        { key = "copy_to_clipboard", type = "bool", label = "Copy path to clipboard", default = false },
+        { key = "hide_inactive", type = "bool", label = "Hide widget when idle", default = false },
+        { key = "replay_enabled", type = "bool", label = "Enable replay buffer", default = false },
+        { key = "replay_duration", type = "int", label = "Replay seconds", default = 30, min = 5, max = 3600,
+          visible_when = { key = "replay_enabled", values = { "true" } } },
+        { key = "replay_storage", type = "select", label = "Replay storage", default = "ram",
+          options = { { value = "ram", label = "RAM" }, { value = "disk", label = "Disk" } },
+          visible_when = { key = "replay_enabled", values = { "true" } } },
+        { key = "restore_portal", type = "bool", label = "Restore portal session", default = false,
+          advanced = true },
+    },
+})
+
 local CHECK_TICKS = 8 -- 8 * 250ms = 2s between process checks
 local PENDING_TICKS = 8
 

meson.build

@@ -433,6 +433,7 @@ _noctalia_sources = files(
   'src/scripting/script_runtime.cpp',
   'src/scripting/script_worker_pool.cpp',
   'src/scripting/scripted_widget_bindings.cpp',
+  'src/scripting/scripted_widget_manifest.cpp',
   'src/shell/bar/bar.cpp',
   'src/shell/clipboard/clipboard_paste.cpp',
   'src/shell/dock/dock.cpp',

src/scripting/scripted_widget_bindings.cpp

@@ -4,6 +4,7 @@
 #include "lualib.h"
 
 #include <algorithm>
+#include <optional>
 #include <string>
 #include <string_view>
 #include <variant>
@@ -136,6 +137,173 @@ namespace {
     return 1;
   }
 
+  // ── Manifest parsing (barWidget.define) ──────────────────────────────────
+
+  std::string tableStringField(lua_State* L, int tableIndex, const char* key, std::string fallback = {}) {
+    lua_getfield(L, tableIndex, key);
+    std::string out = lua_isstring(L, -1) ? std::string(lua_tostring(L, -1)) : std::move(fallback);
+    lua_pop(L, 1);
+    return out;
+  }
+
+  bool tableBoolField(lua_State* L, int tableIndex, const char* key, bool fallback) {
+    lua_getfield(L, tableIndex, key);
+    bool out = lua_isnil(L, -1) ? fallback : (lua_toboolean(L, -1) != 0);
+    lua_pop(L, 1);
+    return out;
+  }
+
+  std::optional<double> tableNumberField(lua_State* L, int tableIndex, const char* key) {
+    lua_getfield(L, tableIndex, key);
+    std::optional<double> out;
+    if (lua_isnumber(L, -1)) {
+      out = lua_tonumber(L, -1);
+    }
+    lua_pop(L, 1);
+    return out;
+  }
+
+  scripting::ManifestFieldType parseFieldType(std::string_view type) {
+    if (type == "bool" || type == "boolean") {
+      return scripting::ManifestFieldType::Bool;
+    }
+    if (type == "int" || type == "integer") {
+      return scripting::ManifestFieldType::Int;
+    }
+    if (type == "double" || type == "number" || type == "float") {
+      return scripting::ManifestFieldType::Double;
+    }
+    if (type == "select" || type == "enum") {
+      return scripting::ManifestFieldType::Select;
+    }
+    if (type == "color") {
+      return scripting::ManifestFieldType::Color;
+    }
+    return scripting::ManifestFieldType::String;
+  }
+
+  void parseFieldDefault(lua_State* L, int fieldIndex, scripting::ManifestField& field) {
+    lua_getfield(L, fieldIndex, "default");
+    switch (field.type) {
+    case scripting::ManifestFieldType::Bool:
+      field.boolDefault = lua_toboolean(L, -1) != 0;
+      break;
+    case scripting::ManifestFieldType::Int:
+    case scripting::ManifestFieldType::Double:
+      field.numberDefault = lua_isnumber(L, -1) ? lua_tonumber(L, -1) : 0.0;
+      break;
+    default:
+      field.stringDefault = lua_isstring(L, -1) ? std::string(lua_tostring(L, -1)) : std::string{};
+      break;
+    }
+    lua_pop(L, 1);
+  }
+
+  void parseFieldOptions(lua_State* L, int fieldIndex, scripting::ManifestField& field) {
+    lua_getfield(L, fieldIndex, "options");
+    if (lua_istable(L, -1)) {
+      const int optionsIndex = lua_gettop(L);
+      const int count = static_cast<int>(lua_objlen(L, optionsIndex));
+      for (int i = 1; i <= count; ++i) {
+        lua_rawgeti(L, optionsIndex, i);
+        if (lua_istable(L, -1)) {
+          const int optIndex = lua_gettop(L);
+          scripting::ManifestSelectOption opt;
+          opt.value = tableStringField(L, optIndex, "value");
+          opt.label = tableStringField(L, optIndex, "label", opt.value);
+          if (!opt.value.empty()) {
+            field.options.push_back(std::move(opt));
+          }
+        } else if (lua_isstring(L, -1)) {
+          std::string value = lua_tostring(L, -1);
+          field.options.push_back(scripting::ManifestSelectOption{.value = value, .label = value});
+        }
+        lua_pop(L, 1);
+      }
+    }
+    lua_pop(L, 1);
+  }
+
+  void parseFieldVisibility(lua_State* L, int fieldIndex, scripting::ManifestField& field) {
+    lua_getfield(L, fieldIndex, "visible_when");
+    if (lua_istable(L, -1)) {
+      const int visIndex = lua_gettop(L);
+      scripting::ManifestVisibility vis;
+      vis.key = tableStringField(L, visIndex, "key");
+      lua_getfield(L, visIndex, "values");
+      if (lua_istable(L, -1)) {
+        const int valuesIndex = lua_gettop(L);
+        const int count = static_cast<int>(lua_objlen(L, valuesIndex));
+        for (int i = 1; i <= count; ++i) {
+          lua_rawgeti(L, valuesIndex, i);
+          if (lua_isstring(L, -1)) {
+            vis.values.emplace_back(lua_tostring(L, -1));
+          } else if (lua_isboolean(L, -1)) {
+            vis.values.emplace_back(lua_toboolean(L, -1) != 0 ? "true" : "false");
+          }
+          lua_pop(L, 1);
+        }
+      }
+      lua_pop(L, 1);
+      if (!vis.key.empty() && !vis.values.empty()) {
+        field.visibleWhen = std::move(vis);
+      }
+    }
+    lua_pop(L, 1);
+  }
+
+  void parseManifest(lua_State* L, int tableIndex, scripting::ScriptWidgetManifest& manifest) {
+    manifest.label = tableStringField(L, tableIndex, "label");
+    manifest.icon = tableStringField(L, tableIndex, "icon");
+    manifest.description = tableStringField(L, tableIndex, "description");
+    manifest.pickable = tableBoolField(L, tableIndex, "pickable", true);
+
+    lua_getfield(L, tableIndex, "settings");
+    if (lua_istable(L, -1)) {
+      const int settingsIndex = lua_gettop(L);
+      const int count = static_cast<int>(lua_objlen(L, settingsIndex));
+      for (int i = 1; i <= count; ++i) {
+        lua_rawgeti(L, settingsIndex, i);
+        if (lua_istable(L, -1)) {
+          const int fieldIndex = lua_gettop(L);
+          scripting::ManifestField field;
+          field.key = tableStringField(L, fieldIndex, "key");
+          if (!field.key.empty()) {
+            field.type = parseFieldType(tableStringField(L, fieldIndex, "type", "string"));
+            field.label = tableStringField(L, fieldIndex, "label", field.key);
+            field.description = tableStringField(L, fieldIndex, "description");
+            field.advanced = tableBoolField(L, fieldIndex, "advanced", false);
+            field.minValue = tableNumberField(L, fieldIndex, "min");
+            field.maxValue = tableNumberField(L, fieldIndex, "max");
+            if (auto step = tableNumberField(L, fieldIndex, "step"); step.has_value()) {
+              field.step = *step;
+            }
+            parseFieldDefault(L, fieldIndex, field);
+            parseFieldOptions(L, fieldIndex, field);
+            parseFieldVisibility(L, fieldIndex, field);
+            manifest.settings.push_back(std::move(field));
+          }
+        }
+        lua_pop(L, 1);
+      }
+    }
+    lua_pop(L, 1);
+  }
+
+  int luau_define(lua_State* L) {
+    auto* context = getContext(L);
+    if (context != nullptr && context->manifestOut != nullptr && lua_istable(L, 1)) {
+      *context->manifestOut = {};
+      parseManifest(L, 1, *context->manifestOut);
+      context->defineCalled = true;
+    }
+    // Abort the chunk during extraction so no top-level side effects run.
+    if (context != nullptr && context->manifestExtractionMode) {
+      luaL_error(L, "__manifest_captured");
+    }
+    return 0;
+  }
+
   const luaL_Reg kWidgetLib[] = {
       {"setText", luau_setText},
       {"setGlyph", luau_setGlyph},
@@ -146,6 +314,7 @@ namespace {
       {"setUpdateInterval", luau_setUpdateInterval},
       {"setVisible", luau_setVisible},
       {"getConfig", luau_getConfig},
+      {"define", luau_define},
       {nullptr, nullptr},
   };
 

src/scripting/scripted_widget_bindings.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#include "scripting/scripted_widget_manifest.h"
 #include "scripting/scripted_widget_types.h"
 
 #include <vector>
@@ -16,6 +17,13 @@ namespace scripting {
     ScriptWidgetPatch patch;
     std::vector<ScriptWidgetSideEffect> sideEffects;
 
+    // Manifest extraction: when `manifestExtractionMode` is set, `barWidget.define`
+    // captures its table into `manifestOut`, flips `defineCalled`, then aborts the
+    // chunk so no later top-level side effects run.
+    bool manifestExtractionMode = false;
+    bool defineCalled = false;
+    ScriptWidgetManifest* manifestOut = nullptr;
+
     void beginCall(ScriptWidgetSnapshot nextSnapshot) {
       snapshot = std::move(nextSnapshot);
       patch = {};