clogs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c5a5068ca08f8566250559ac8272e88a638437c920ede77a3dd7e737db665ef1
+  data.tar.gz: a05eb6a0560bc9d6cb44d0edbd39e19ff4d788bd601ad7698fed1658329710f3
+SHA512:
+  metadata.gz: '0383ca3af192cd8644378292bd4171d16ee9499dbd6370963b281559699f633b0428ee667bc1fb77f9e6449591526d921721cd4e89f172251b6948a39b67749f'
+  data.tar.gz: ce3f150fe9f1250c5e51a196a9105bec2d7d1b173ec86289169b6172225bfe5fef1a61047b56c81becd0bfbb94d624b2802043d853c2a0d9ff1cba03d9c4820c

data/README.md

@@ -0,0 +1,83 @@
+# Clogs
+
+**Shoes, worn over libui.**
+
+Clogs runs [Shoes](https://github.com/shoes/shoes-deprecated) programs on plain
+CRuby. No browser engine, no JVM — just [libui](https://github.com/libui-ng/libui-ng),
+a small native widget library that ships as a prebuilt shared object for Linux,
+macOS and Windows.
+
+```ruby
+require "clogs"
+
+Shoes.app(title: "Hello", width: 400, height: 200) do
+  para "Hello, ", strong("Shoes"), "!", size: :title
+  button("Push me") { @note.replace "Aha! Clicked." }
+  @note = para "Nothing pushed so far"
+end
+```
+
+```
+gem install clogs
+ruby hello.rb
+```
+
+## How it fits together
+
+The Shoes API itself comes from [Lacci](https://github.com/scarpe-team/scarpe),
+the display-independent half of Scarpe. Lacci owns the DSL and the drawable
+tree; Clogs is a Lacci *display service* and owns the pixels.
+
+```
+your Shoes program
+        |
+      Lacci          the Shoes DSL, drawable tree, events
+        |
+      Clogs          layout, painting, widgets, input
+        |
+      libui          one native window, one canvas
+```
+
+You can also select it explicitly, which is useful when the same program should
+run under Scarpe's webview backend too:
+
+```
+SCARPE_DISPLAY_SERVICE=clogs ruby my_app.rb
+```
+
+## What it looks like
+
+Clogs paints the entire Shoes document into a single libui canvas, including the
+widgets. That is not a shortcut: libui has no way to place a native control at an
+arbitrary position, and Shoes needs exactly that. The trade-offs — and a tested
+feature-by-feature matrix — are in
+[docs/libui_shoes_coverage.md](docs/libui_shoes_coverage.md).
+
+The short version: layout, text, links, art drawables, images, widgets, events,
+animation and dialogs all work. Video, sound, blur and multiple windows do not.
+
+## Development
+
+```
+cd clogs
+bundle install
+rake test                                  # unit tests plus real windowed runs
+ruby -Ilib examples/kitchen_sink.rb        # see it
+```
+
+The tests open real windows, so on a headless machine run them under Xvfb:
+
+```
+xvfb-run -a rake test
+```
+
+Two environment variables make Shoes apps scriptable, which is how Clogs tests
+itself and how you can screenshot an app from CI:
+
+```
+CLOGS_EXIT_AFTER_MS=800 CLOGS_SCREENSHOT=shot.png ruby -Ilib examples/kitchen_sink.rb
+```
+
+## Licence
+
+MIT.

data/examples/kitchen_sink.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# A tour of what Clogs can draw. Run it with:
+#
+#   ruby -Iclogs/lib clogs/examples/kitchen_sink.rb
+
+require "clogs"
+
+Shoes.app(title: "Clogs kitchen sink", width: 640, height: 620) do
+  stack do
+    background rgb(250, 250, 252)
+
+    title "Clogs", stroke: rgb(40, 40, 90)
+    para "Shoes drawables rendered by ", strong("libui"), ", with ", em("emphasis"),
+      ", ", code("code"), " and a ", link("link") { @status.replace "You clicked the link!" }, "."
+
+    flow do
+      button("A button") { @status.replace "Button pushed." }
+      check
+      radio "group"
+      radio "group"
+    end
+
+    @status = para "Nothing has happened yet.", stroke: rgb(120, 0, 0)
+
+    flow do
+      edit_line text: "edit me"
+      list_box items: ["one", "two", "three"]
+    end
+
+    edit_box text: "A multi-line edit box.\nType into me.", width: 400, height: 90
+
+    progress fraction: 0.35
+
+    stack(width: 620, height: 170) do
+      background rgb(255, 255, 255)
+      border rgb(200, 200, 210), strokewidth: 2
+
+      fill rgb(220, 60, 60)
+      stroke rgb(60, 0, 0)
+      rect 20, 20, 120, 60
+
+      fill rgb(60, 120, 220)
+      oval 170, 20, 100, 60
+
+      nostroke
+      fill rgb(250, 200, 40)
+      star 320, 20, 6, 34, 16
+
+      stroke rgb(0, 140, 0)
+      strokewidth 4
+      line 20, 110, 300, 130
+
+      nofill
+      stroke rgb(120, 60, 200)
+      strokewidth 3
+      shape do
+        move_to 340, 100
+        line_to 380, 60
+        line_to 420, 140
+        line_to 460, 90
+      end
+    end
+  end
+end

data/lib/clogs/app.rb

@@ -0,0 +1,398 @@
+# frozen_string_literal: true
+
+require_relative "drawable"
+require_relative "canvas"
+require_relative "dialogs"
+require_relative "clipboard"
+
+module Clogs
+  # The display side of Shoes::App: one libui window, one canvas, and the
+  # plumbing that turns libui's callbacks into Shoes events.
+  class App < Drawable
+    class << self
+      attr_accessor :instance
+
+      # Set synchronously while a `builtin` event is being handled, so that
+      # `ask`/`confirm` can return a value even on Lacci versions that have no
+      # response channel of their own.
+      attr_accessor :builtin_response
+    end
+
+    attr_reader :window, :canvas, :document_root, :mouse_state
+
+    def initialize(properties)
+      super
+      App.instance = self
+      @timers = []
+      @needs_layout = true
+      @focused = nil
+      @hovered = nil
+      @mouse_state = [0, 0, 0]
+
+      bind_shoes_event(event_name: "init") { init }
+      bind_shoes_event(event_name: "run") { run }
+      bind_shoes_event(event_name: "destroy") { destroy }
+      Shoes::DisplayService.subscribe_to_event("builtin", nil) do |cmd, args|
+        App.builtin_response = builtin(cmd, args)
+      end
+    end
+
+    def app
+      self
+    end
+
+    def title
+      style(:title) || "Shoes"
+    end
+
+    def app_width
+      (style(:width) || 480).to_i
+    end
+
+    def app_height
+      (style(:height) || 420).to_i
+    end
+
+    def init
+      UI::L.init unless @initialized
+      @initialized = true
+
+      @window = UI::L.new_window(title, app_width, app_height, 0)
+      UI::L.window_set_margined(@window, 0)
+      UI::L.window_on_closing(@window) do
+        quit
+        0
+      end
+
+      @canvas = Canvas.new
+      @canvas.on_draw = method(:on_draw)
+      @canvas.on_mouse = method(:on_mouse)
+      @canvas.on_key = method(:on_key)
+      @canvas.on_crossed = method(:on_crossed)
+
+      # An area needs a stretchy box around it or libui gives it no size.
+      box = UI::L.new_vertical_box
+      UI::L.box_append(box, @canvas.area, 1)
+      UI::L.window_set_child(@window, box)
+    end
+
+    def run
+      UI::L.control_show(@window)
+      @running = true
+      arm_timers
+      install_test_hooks
+      UI::L.main
+      # libui aborts on exit if a control is still alive, so tear the window
+      # down explicitly. Destroying the window destroys its children.
+      UI::L.control_destroy(@window) if @window
+      @window = nil
+      # Anything that runs after the window is gone -- at_exit handlers, an
+      # app's own shutdown code -- must not touch the area again. Queueing a
+      # redraw on a destroyed area segfaults.
+      @canvas = nil
+      UI::L.uninit if @initialized
+    end
+
+    # Hooks for automated testing: run the app for a fixed time, optionally
+    # capture the screen, then quit. Used by Clogs' own visual tests and handy
+    # for any Shoes app under CI.
+    #
+    #   CLOGS_EXIT_AFTER_MS=800 CLOGS_SCREENSHOT=out.png ruby app.rb
+    def install_test_hooks
+      ms = ENV["CLOGS_EXIT_AFTER_MS"]&.to_i
+      return if ms.nil? || ms <= 0
+
+      @exit_deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + ms / 1000.0
+      add_timer(ms, repeat: false) { finish_test_run }
+    end
+
+    # A busy app -- an animation that cannot keep up on a slow machine, say --
+    # can starve a one-shot timer indefinitely. The deadline is therefore also
+    # checked from the paint callback, so the run ends as long as anything is
+    # still happening at all.
+    def check_test_deadline
+      return unless @exit_deadline
+      return if Process.clock_gettime(Process::CLOCK_MONOTONIC) < @exit_deadline
+
+      finish_test_run
+    end
+
+    def finish_test_run
+      return if @exit_deadline.nil?
+
+      @exit_deadline = nil
+      capture_screenshot(ENV["CLOGS_SCREENSHOT"]) if ENV["CLOGS_SCREENSHOT"]
+      quit
+    end
+
+    def capture_screenshot(path)
+      # ImageMagick's `import` is the only dependency-free way to do this on
+      # X11; elsewhere the screenshot is simply skipped.
+      system("import", "-window", "root", path, err: File::NULL)
+    end
+
+    def destroy
+      return if @destroyed
+
+      @destroyed = true
+      UI::L.quit
+    end
+
+    def quit
+      notify("destroy")
+      destroy
+    end
+
+    def document_root=(root)
+      @document_root = root
+      root.app = self
+      needs_layout!
+    end
+
+    def needs_layout!
+      @needs_layout = true
+      redraw!
+    end
+
+    def redraw!
+      return if @destroyed
+
+      @canvas&.redraw
+    end
+
+    # ---- painting -----------------------------------------------------
+
+    BACKGROUND = [255, 255, 255, 255].freeze
+
+    def on_draw(painter, _params)
+      check_test_deadline
+      painter.fill_rect(0, 0, painter.width, painter.height, BACKGROUND)
+      return unless @document_root
+
+      if @needs_layout || @last_width != painter.width
+        @document_root.measure(painter.width)
+        @last_width = painter.width
+        @needs_layout = false
+      end
+      @document_root.paint(painter, 0, 0)
+      open_list_boxes.each { |lb| lb.draw_overlay(painter) }
+    rescue StandardError => e
+      report_error(e)
+    end
+
+    def open_list_boxes
+      return [] unless @document_root
+
+      found = []
+      @document_root.each_peer { |peer| found << peer if peer.is_a?(ListBox) && peer.open? }
+      found
+    end
+
+    # ---- input --------------------------------------------------------
+
+    def peers_at(x, y)
+      return [] unless @document_root
+
+      hits = []
+      @document_root.each_peer { |peer| hits << peer if peer.contains?(x, y) }
+      hits
+    end
+
+    def topmost_clickable(x, y)
+      peers_at(x, y).reverse.find(&:clickable?)
+    end
+
+    def on_mouse(event)
+      @mouse_state = [event.button_down? ? 1 : 0, event.x.round, event.y.round]
+      Shoes::DisplayService.mouse_state = @mouse_state if Shoes::DisplayService.respond_to?(:mouse_state=)
+
+      update_hover(event)
+      notify_subscribers("motion", event.x.round, event.y.round,
+        event.modifiers.anybits?(UI::MOD_CTRL), event.modifiers.anybits?(UI::MOD_SHIFT))
+
+      if event.down.positive?
+        handle_press(event)
+      elsif event.up.positive?
+        handle_release(event)
+      end
+    rescue StandardError => e
+      report_error(e)
+    end
+
+    def handle_press(event)
+      # A click outside an open drop-down closes it.
+      open_list_boxes.each { |lb| lb.close unless lb.contains?(event.x, event.y) || lb.overlay_contains?(event.x, event.y) }
+
+      target = open_list_boxes.find { |lb| lb.overlay_contains?(event.x, event.y) } ||
+        topmost_clickable(event.x, event.y)
+      set_focus(target&.focusable? ? target : nil)
+      target&.on_click(event.x, event.y, event.down)
+      @pressed = target
+      notify_subscribers("click", event.down, event.x.round, event.y.round)
+    end
+
+    def handle_release(event)
+      @pressed&.on_release(event.x, event.y, event.up)
+      @pressed = nil
+      notify_subscribers("release", event.up, event.x.round, event.y.round)
+    end
+
+    def update_hover(event)
+      target = peers_at(event.x, event.y).reverse.find { |p| p.clickable? || p.is_a?(Control) }
+      return if target == @hovered
+
+      if @hovered
+        @hovered.on_mouse_leave if @hovered.respond_to?(:on_mouse_leave)
+        @hovered.notify("leave")
+      end
+      @hovered = target
+      if target
+        target.on_mouse_enter if target.respond_to?(:on_mouse_enter)
+        target.notify("hover")
+      end
+      notify_subscribers("hover") if target
+      notify_subscribers("leave") unless target
+    end
+
+    def set_focus(peer)
+      return if peer == @focused
+
+      @focused&.focused = false
+      @focused&.focus_lost
+      @focused = peer
+      return unless peer
+
+      peer.focused = true
+      peer.focus_gained
+    end
+
+    def on_key(event)
+      return false if @destroyed
+
+      if @focused&.on_key(event)
+        redraw!
+        return true
+      end
+      name = key_name(event)
+      return false unless name && !event.up
+
+      notify_subscribers("keypress", name)
+      true
+    rescue StandardError => e
+      report_error(e)
+      false
+    end
+
+    # Shoes reports keys as single characters, names like "up", or
+    # "control_x" style combinations.
+    def key_name(event)
+      base = if event.ext
+        event.ext.to_s
+      elsif event.char
+        case event.char
+        when "\b", "\x7F" then "backspace"
+        when "\r", "\n" then "\n"
+        when "\t" then "tab"
+        when " " then " "
+        else event.char
+        end
+      end
+      return nil unless base
+
+      mods = []
+      mods << "control" if event.ctrl?
+      mods << "alt" if event.alt?
+      mods << "shift" if event.shift? && base.length > 1
+      mods.empty? ? base : (mods + [base]).join("_")
+    end
+
+    def on_crossed(left)
+      return unless left
+
+      @hovered&.on_mouse_leave if @hovered.respond_to?(:on_mouse_leave)
+      @hovered = nil
+      redraw!
+    end
+
+    # ---- subscriptions and timers -------------------------------------
+
+    def subscriptions
+      found = []
+      @document_root&.each_peer { |peer| found << peer if peer.is_a?(SubscriptionItem) }
+      found
+    end
+
+    def notify_subscribers(api_name, *args)
+      subscriptions.each do |sub|
+        sub.notify(api_name, *args) if sub.api_name == api_name
+      end
+    end
+
+    # libui's timer callback returns nonzero to keep firing.
+    #
+    # Timers may only be armed once the main loop is running: Shoes programs
+    # routinely call `animate` or `every` while the app is still being built,
+    # and handing libui a timer before then crashes it. Queue those and arm
+    # them when the loop starts.
+    def add_timer(interval_ms, repeat: true, &block)
+      interval_ms = 1 if interval_ms.to_i < 1
+      unless @running
+        (@pending_timers ||= []) << [interval_ms, repeat, block]
+        return
+      end
+
+      # Arming a timer from inside a libui callback re-enters the loop's own
+      # bookkeeping and crashes; queue_main defers it to a safe point. Shoes
+      # programs create timers from event handlers all the time.
+      UI::L.queue_main { arm_timer(interval_ms, repeat, block) }
+    end
+
+    def arm_timers
+      pending = @pending_timers || []
+      @pending_timers = nil
+      pending.each { |interval, repeat, block| arm_timer(interval, repeat, block) }
+    end
+
+    # The libui binding builds the callback itself when given a block, which
+    # is the only way to get the `int (*)(void *)` signature right; a
+    # hand-rolled closure with the wrong arity corrupts the stack.
+    # Returning nonzero keeps the timer running.
+    def arm_timer(interval_ms, repeat, block)
+      UI::L.timer(interval_ms) do
+        if @destroyed
+          0
+        else
+          begin
+            block.call
+          rescue StandardError => e
+            report_error(e)
+          end
+          repeat ? 1 : 0
+        end
+      end
+    end
+
+    # ---- builtins -----------------------------------------------------
+
+    def builtin(cmd, args)
+      case cmd.to_s
+      when "alert" then Dialogs.alert(@window, args[0])
+      when "confirm" then Dialogs.confirm(@window, args[0])
+      when "ask" then Dialogs.ask(@window, args[0])
+      when "ask_open_file" then Dialogs.open_file(@window)
+      when "ask_save_file" then Dialogs.save_file(@window)
+      when "ask_open_folder" then Dialogs.open_folder(@window)
+      when "ask_color" then nil
+      when "font" then nil
+      end
+    rescue StandardError => e
+      report_error(e)
+      nil
+    end
+
+    def report_error(error)
+      warn "Clogs error: #{error.class}: #{error.message}"
+      warn error.backtrace.first(12).join("\n") if error.backtrace
+    end
+  end
+end

data/lib/clogs/canvas.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative "ui"
+require_relative "painter"
+
+module Clogs
+  # Owns a uiArea and turns libui's callbacks into ordinary Ruby ones.
+  #
+  # Everything Clogs draws lives in a single area per window. That is not a
+  # stylistic choice: libui has no container that positions native controls at
+  # arbitrary coordinates, and Shoes' layout model requires exactly that. So
+  # Clogs paints the whole Shoes document itself and synthesises the widgets
+  # Shoes needs. See docs/libui_shoes_coverage.md.
+  class Canvas
+    attr_reader :area
+    attr_accessor :on_draw, :on_mouse, :on_key, :on_crossed
+
+    def initialize(scrolling: false, scroll_width: 0, scroll_height: 0)
+      @handler = UI.malloc(UI::L::FFI::AreaHandler)
+
+      @handler.Draw = UI.callback(0, [1, 1, 1]) do |_h, _area, params|
+        p = UI::L::FFI::AreaDrawParams.new(params)
+        painter = Painter.new(p.Context, p.AreaWidth, p.AreaHeight)
+        @on_draw&.call(painter, p)
+        0
+      end
+
+      @handler.MouseEvent = UI.callback(0, [1, 1, 1]) do |_h, _area, evt|
+        e = UI::L::FFI::AreaMouseEvent.new(evt)
+        @on_mouse&.call(mouse_event(e))
+        0
+      end
+
+      @handler.MouseCrossed = UI.callback(0, [1, 1, 0]) do |_h, _area, left|
+        @on_crossed&.call(left != 0)
+        0
+      end
+
+      @handler.DragBroken = UI.callback(0, [1, 1]) { 0 }
+
+      @handler.KeyEvent = UI.callback(1, [1, 1, 1]) do |_h, _area, evt|
+        e = UI::L::FFI::AreaKeyEvent.new(evt)
+        handled = @on_key&.call(key_event(e))
+        handled ? 1 : 0
+      end
+
+      @area = if scrolling
+        UI::L.new_scrolling_area(@handler, scroll_width, scroll_height)
+      else
+        UI::L.new_area(@handler)
+      end
+      @scrolling = scrolling
+    end
+
+    def redraw
+      UI::L.area_queue_redraw_all(@area)
+    end
+
+    def set_scroll_size(w, h)
+      return unless @scrolling
+
+      UI::L.area_set_size(@area, w.to_i, h.to_i)
+    end
+
+    def scroll_to(x, y, w, h)
+      return unless @scrolling
+
+      UI::L.area_scroll_to(@area, x, y, w, h)
+    end
+
+    private
+
+    MouseEvent = Struct.new(:x, :y, :area_width, :area_height, :down, :up, :count, :modifiers, :held, keyword_init: true) do
+      def button_down?
+        held.anybits?(1)
+      end
+    end
+
+    def mouse_event(e)
+      MouseEvent.new(
+        x: e.X, y: e.Y, area_width: e.AreaWidth, area_height: e.AreaHeight,
+        down: e.Down, up: e.Up, count: e.Count, modifiers: e.Modifiers, held: e.Held1To64
+      )
+    end
+
+    KeyEvent = Struct.new(:char, :ext, :modifier, :modifiers, :up, keyword_init: true) do
+      def ctrl?
+        modifiers.anybits?(UI::MOD_CTRL)
+      end
+
+      def shift?
+        modifiers.anybits?(UI::MOD_SHIFT)
+      end
+
+      def alt?
+        modifiers.anybits?(UI::MOD_ALT)
+      end
+    end
+
+    # libui reports the *unshifted* key for an area, so "shift" plus "1" is
+    # reported as "1" rather than "!". Applying shift here keeps the rest of
+    # Clogs working in characters. The symbol half of the table assumes a US
+    # layout; letters are correct everywhere.
+    SHIFTED = {
+      "1" => "!", "2" => "@", "3" => "#", "4" => "$", "5" => "%", "6" => "^",
+      "7" => "&", "8" => "*", "9" => "(", "0" => ")", "-" => "_", "=" => "+",
+      "[" => "{", "]" => "}", "\\" => "|", ";" => ":", "'" => '"', "," => "<",
+      "." => ">", "/" => "?", "`" => "~"
+    }.freeze
+
+    def key_event(e)
+      raw = e.Key
+      char = case raw
+      when nil, 0 then nil
+      when Integer then raw.chr
+      else raw.to_s.empty? ? nil : raw.to_s
+      end
+
+      if char && e.Modifiers.anybits?(UI::MOD_SHIFT)
+        char = SHIFTED[char] || char.upcase
+      end
+
+      KeyEvent.new(
+        char: char, ext: UI::EXT_KEYS[e.ExtKey], modifier: e.Modifier,
+        modifiers: e.Modifiers, up: e.Up != 0
+      )
+    end
+  end
+end