scarpe 0.2.2 → 0.3.0

data/lib/scarpe/wv/app.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-class Scarpe
-  # Scarpe::WebviewApp must only be used from the main thread, due to GTK+ limitations.
-  class WebviewApp < WebviewWidget
+module Scarpe::Webview
+  # Scarpe::Webview::App must only be used from the main thread, due to GTK+ limitations.
+  class App < Drawable # App inherits from Drawable to set up linkable IDs and event methods
     attr_reader :control_interface
 
     attr_writer :shoes_linkable_id
@@ -10,22 +10,16 @@ class Scarpe
     def initialize(properties)
       super
 
-      # It's possible to provide a Ruby script by setting
-      # SCARPE_TEST_CONTROL to its file path. This can
-      # allow pre-setting test options or otherwise
-      # performing additional actions not written into
-      # the Shoes app itself.
-      #
-      # The control interface is what lets these files see
-      # events, specify overrides and so on.
+      # Scarpe's ControlInterface sets up event handlers
+      # for the display service that aren't sent to
+      # Lacci (Shoes). In general it's used for setup
+      # and additional control or testing, outside the
+      # Shoes app. This is how CatsCradle and Shoes-Spec
+      # set up testing, for instance.
       @control_interface = ControlInterface.new
-      if ENV["SCARPE_TEST_CONTROL"]
-        require "scarpe/components/unit_test_helpers"
-        @control_interface.instance_eval File.read(ENV["SCARPE_TEST_CONTROL"])
-      end
 
       # TODO: rename @view
-      @view = Scarpe::WebWrangler.new title: @title,
+      @view = Scarpe::Webview::WebWrangler.new title: @title,
         width: @width,
         height: @height,
         resizable: @resizable
@@ -63,6 +57,8 @@ class Scarpe
     def run
       @control_interface.dispatch_event(:init)
 
+      @view.empty_page = empty_page_element
+
       # This takes control of the main thread and never returns. And it *must* be run from
       # the main thread. And it stops any Ruby background threads.
       # That's totally cool and normal, right?
@@ -80,14 +76,18 @@ class Scarpe
       end
     end
 
-    # All JS callbacks to Scarpe widgets are dispatched
+    # All JS callbacks to Scarpe drawables are dispatched
     # via this handler
     def handle_callback(name, *args)
-      @callbacks[name].call(*args)
+      if @callbacks.key?(name)
+        @callbacks[name].call(*args)
+      else
+        raise Scarpe::UnknownEventTypeError, "No such Webview callback: #{name.inspect}!"
+      end
     end
 
     # Bind a Scarpe callback name; see handle_callback above.
-    # See Scarpe::Widget for how the naming is set up
+    # See Scarpe::Drawable for how the naming is set up
     def bind(name, &block)
       @callbacks[name] = block
     end
@@ -97,7 +97,7 @@ class Scarpe
     #
     # @return [void]
     def request_redraw!
-      wrangler = WebviewDisplayService.instance.wrangler
+      wrangler = DisplayService.instance.wrangler
       if wrangler.is_running
         wrangler.replace(@document_root.to_html)
       end

data/lib/scarpe/wv/arc.rb

@@ -1,56 +1,13 @@
 # frozen_string_literal: true
 
-class Scarpe
-  class WebviewArc < Scarpe::WebviewWidget
+module Scarpe::Webview
+  class Arc < Drawable
     def initialize(properties)
       super(properties)
     end
 
-    def element(&block)
-      HTML.render do |h|
-        h.div(id: html_id, style: style) do
-          h.svg(width: @width, height: @height) do
-            h.path(d: arc_path)
-          end
-          block.call(h) if block_given?
-        end
-      end
-    end
-
-    protected
-
-    def style
-      super.merge({
-        left: "#{@left}px",
-        top: "#{@top}px",
-        width: "#{@width}px",
-        height: "#{@height}px",
-      })
-    end
-
-    private
-
-    def arc_path
-      center_x = @width / 2
-      center_y = @height / 2
-      radius_x = @width / 2
-      radius_y = @height / 2
-      start_angle_degrees = radians_to_degrees(@angle1) % 360
-      end_angle_degrees = radians_to_degrees(@angle2) % 360
-      large_arc_flag = (end_angle_degrees - start_angle_degrees) % 360 > 180 ? 1 : 0
-
-      "M#{center_x} #{center_y} L#{@width} #{center_y} " \
-        "A#{radius_x} #{radius_y} 0 #{large_arc_flag} 0 " \
-        "#{center_x + radius_x * Math.cos(degrees_to_radians(end_angle_degrees))} " \
-        "#{center_y + radius_y * Math.sin(degrees_to_radians(end_angle_degrees))} Z"
-    end
-
-    def degrees_to_radians(degrees)
-      degrees * Math::PI / 180
-    end
-
-    def radians_to_degrees(radians)
-      radians * (180.0 / Math::PI)
+    def element
+      render("arc")
     end
   end
 end

data/lib/scarpe/wv/arrow.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Scarpe::Webview
+  class Arrow < Drawable
+    def element
+      render("arrow")
+    end
+  end
+end

data/lib/scarpe/wv/button.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-class Scarpe
-  class WebviewButton < WebviewWidget
+module Scarpe::Webview
+  class Button < Drawable
     def initialize(properties)
       super
 
@@ -10,43 +10,15 @@ class Scarpe
         # This will be sent to the bind_self_event in Button
         send_self_event(event_name: "click")
       end
-    end
 
-    def element
-      HTML.render do |h|
-        h.button(id: html_id, onclick: handler_js_code("click"), style: style) do
-          @text
-        end
+      bind("hover") do
+        # This will be sent to the bind_self_event in Button
+        send_self_event(event_name: "hover")
       end
     end
 
-    protected
-
-    def style
-      styles = super
-
-      styles[:"background-color"] = @color
-      styles[:"padding-top"] = @padding_top
-      styles[:"padding-bottom"] = @padding_bottom
-      styles[:color] = @text_color
-      styles[:width] = Dimensions.length(@width) if @width
-      styles[:height] = Dimensions.length(@height) if @height
-      styles[:"font-size"] = @font_size
-
-      styles[:top] = Dimensions.length(@top) if @top
-      styles[:left] = Dimensions.length(@left) if @left
-      styles[:position] = "absolute" if @top || @left
-      styles[:"font-size"] = Dimensions.length(font_size) if @size
-      styles[:"font-family"] = @font if @font
-      styles[:color] = rgb_to_hex(@stroke) if @stroke
-
-      styles
-    end
-
-    def font_size
-      font_size = @size.is_a?(Symbol) ? SIZES[@size] : @size
-
-      Dimensions.length(font_size)
+    def element
+      render("button")
     end
   end
 end

data/lib/scarpe/wv/check.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-class Scarpe
-  class WebviewCheck < Scarpe::WebviewWidget
+module Scarpe::Webview
+  class Check < Drawable
     attr_reader :text
 
     def initialize(properties)
@@ -21,9 +21,7 @@ class Scarpe
     end
 
     def element
-      HTML.render do |h|
-        h.input(type: :checkbox, id: html_id, onclick: handler_js_code("click"), value: "hmm #{text}", checked: @checked, style:)
-      end
+      render("check")
     end
   end
 end

data/lib/scarpe/wv/control_interface.rb

@@ -10,19 +10,22 @@
 # And if you depend on this from the framework, I'll add a check-mode that
 # never dispatches any events to any handlers. Do NOT test me on this.
 
-class Scarpe
+module Scarpe::Webview
   class ControlInterface
     include Shoes::Log
 
     SUBSCRIBE_EVENTS = [:init, :shutdown, :next_redraw, :every_redraw, :next_heartbeat, :every_heartbeat]
     DISPATCH_EVENTS = [:init, :shutdown, :redraw, :heartbeat]
+    INVALID_SYSTEM_COMPONENTS_MESSAGE = "Must pass non-nil app and wrangler to ControlInterface#set_system_components!"
+    CONTROL_INTERFACE_INIT_MESSAGE = "ControlInterface code needs to be wrapped in handlers like on_event(:init) " +
+      "to make sure they have access to app, doc_root, wrangler, etc!"
 
     attr_writer :doc_root
     attr_reader :do_shutdown
 
     # The control interface needs to see major system components to hook into their events
     def initialize
-      log_init("WV::ControlInterface")
+      log_init("Webview::ControlInterface")
 
       @do_shutdown = false
       @event_handlers = {}
@@ -35,11 +38,15 @@ class Scarpe
 
     # This should get called once, from Shoes::App
     def set_system_components(app:, doc_root:, wrangler:)
-      unless app && wrangler
-        @log.error("False app passed to set_system_components!") unless app
-        @log.error("False wrangler passed to set_system_components!") unless wrangler
-        raise "Must pass non-nil app and wrangler to ControlInterface#set_system_components!"
+      unless app
+        @log.error("False app passed to set_system_components!")
+        raise Scarpe::MissingAppError, INVALID_SYSTEM_COMPONENTS_MESSAGE
       end
+      unless wrangler
+        @log.error("False wrangler passed to set_system_components!")
+        raise Scarpe::MissingWranglerError, INVALID_SYSTEM_COMPONENTS_MESSAGE
+      end
+
       @app = app
       @doc_root = doc_root # May be nil at this point
       @wrangler = wrangler
@@ -50,28 +57,19 @@ class Scarpe
     end
 
     def app
-      unless @app
-        raise "ControlInterface code needs to be wrapped in handlers like on_event(:init) " +
-          "to make sure they have access to app, doc_root, wrangler, etc!"
-      end
+      raise Scarpe::MissingAppError, CONTROL_INTERFACE_INIT_MESSAGE unless @app
 
       @app
     end
 
     def doc_root
-      unless @doc_root
-        raise "ControlInterface code needs to be wrapped in handlers like on_event(:init) " +
-          "to make sure they have access to app, doc_root, wrangler, etc!"
-      end
+      raise Scarpe::MissingDocRootError, CONTROL_INTERFACE_INIT_MESSAGE unless @doc_root
 
       @doc_root
     end
 
     def wrangler
-      unless @wrangler
-        raise "ControlInterface code needs to be wrapped in handlers like on_event(:init) " +
-          "to make sure they have access to app, doc_root, wrangler, etc!"
-      end
+      raise Scarpe::MissingWranglerError, CONTROL_INTERFACE_INIT_MESSAGE unless @wrangler
 
       @wrangler
     end
@@ -82,7 +80,7 @@ class Scarpe
     # On recognised events, this sets a handler for that event
     def on_event(event, &block)
       unless SUBSCRIBE_EVENTS.include?(event)
-        raise "Illegal subscribe to event #{event.inspect}! Valid values are: #{SUBSCRIBE_EVENTS.inspect}"
+        raise Scarpe::IllegalSubscribeEventError, "Illegal subscribe to event #{event.inspect}! Valid values are: #{SUBSCRIBE_EVENTS.inspect}"
       end
 
       @unsub_id ||= 0
@@ -97,7 +95,7 @@ class Scarpe
       @log.debug("CTL event #{event.inspect} #{args.inspect} #{keywords.inspect}")
 
       unless DISPATCH_EVENTS.include?(event)
-        raise "Illegal dispatch of event #{event.inspect}! Valid values are: #{DISPATCH_EVENTS.inspect}"
+        raise Scarpe::IllegalDispatchEventError, "Illegal dispatch of event #{event.inspect}! Valid values are: #{DISPATCH_EVENTS.inspect}"
       end
 
       if @do_shutdown

data/lib/scarpe/wv/document_root.rb

@@ -1,8 +1,85 @@
 # frozen_string_literal: true
 
-class Scarpe
-  # A WebviewDocumentRoot is a WebviewFlow, with all the same properties
-  # and basic behavior.
-  class WebviewDocumentRoot < Scarpe::WebviewFlow
+module Scarpe::Webview
+  # A DocumentRoot is a {Scarpe::Webview::Flow}, with all the same properties
+  # and basic behavior. It also reserves space for Builtins like fonts, alerts,
+  # etc. which don't have individual {Shoes::Drawable} objects.
+  class DocumentRoot < Flow
+    def initialize(properties)
+      super
+
+      @fonts = []
+      @alerts = []
+
+      bind_shoes_event(event_name: "builtin") do |cmd_name, args|
+        case cmd_name
+        when "font"
+          @fonts << args[0]
+          # Can't just create font_updater and alert_updater on initialize - not everything is set up
+          @font_updater ||= Scarpe::Webview::WebWrangler::ElementWrangler.new("root-fonts")
+          @font_updater.inner_html = font_contents
+        when "alert"
+          bind_ok_event
+          @alerts << args[0]
+          @alert_updater ||= Scarpe::Webview::WebWrangler::ElementWrangler.new("root-alerts")
+          @alert_updater.inner_html = alert_contents
+        else
+          raise Scarpe::UnknownBuiltinCommandError, "Unexpected builtin command: #{cmd_name.inspect}!"
+        end
+      end
+    end
+
+    def element(&block)
+      contents = block ? block.call : ""
+      super do
+        contents + HTML.render do |h|
+          h.div(id: "root-fonts") do
+            font_contents
+          end
+          h.div(id: "root-alerts") do
+            alert_contents
+          end
+        end
+      end
+    end
+
+    private
+
+    # This needs to occur after initialize() because the app isn't yet allocated initially,
+    # so we can't call bind() for app events yet.
+    def bind_ok_event
+      return if @ok_event_setup_done
+
+      @ok_event_setup_done = true
+
+      # Done with the alert(s), delete them
+      bind("OK") do
+        @alerts = []
+        needs_update!
+      end
+    end
+
+    def font_contents
+      HTML.render do |h|
+        @fonts.each do |font|
+          h.link(href: font, rel: "stylesheet")
+          h.style do
+            font_name = File.basename(font, ".*")
+            <<~CSS
+              @font-face {
+                font-family: #{font_name};
+                src: url("data:font/truetype;base64,#{encode_file_to_base64(font)}") format('truetype');
+              }
+            CSS
+          end
+        end
+      end
+    end
+
+    def alert_contents
+      @alerts.map do |alert_text|
+        render("alert", { "text" => alert_text, "event_name" => "OK" })
+      end.join + " "
+    end
   end
 end

data/lib/scarpe/wv/{widget.rb → drawable.rb}

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
-class Scarpe
-  # The WebviewWidget parent class helps connect a Webview widget with
+module Scarpe::Webview
+  # The Webview::Drawable parent class helps connect a Webview drawable with
   # its Shoes equivalent, render itself to the Webview DOM, handle
   # Javascript events and generally keep things working in Webview.
-  class WebviewWidget < Shoes::Linkable
+  class Drawable < Shoes::Linkable
+    # This will pick up the log implementation from wv.rb
     include Shoes::Log
 
     class << self
@@ -12,55 +13,59 @@ class Scarpe
       def display_class_for(scarpe_class_name)
         scarpe_class = Shoes.const_get(scarpe_class_name)
         unless scarpe_class.ancestors.include?(Shoes::Linkable)
-          raise "Scarpe Webview can only get display classes for Shoes " +
-            "linkable widgets, not #{scarpe_class_name.inspect}!"
+          raise Scarpe::InvalidClassError, "Scarpe Webview can only get display classes for Shoes " +
+            "linkable drawables, not #{scarpe_class_name.inspect}!"
         end
 
-        klass = Scarpe.const_get("Webview" + scarpe_class_name.split("::")[-1])
+        klass = Scarpe::Webview.const_get(scarpe_class_name.split("::")[-1])
         if klass.nil?
-          raise "Couldn't find corresponding Scarpe Webview class for #{scarpe_class_name.inspect}!"
+          raise Scarpe::MissingClassError, "Couldn't find corresponding Scarpe Webview class for #{scarpe_class_name.inspect}!"
         end
 
         klass
       end
     end
 
-    # The Shoes ID corresponding to the Shoes widget for this Webview widget
+    # The Shoes ID corresponding to the Shoes drawable for this Webview drawable
     attr_reader :shoes_linkable_id
 
-    # The WebviewWidget parent of this widget
+    # The Webview::Drawable parent of this drawable
     attr_reader :parent
 
-    # An array of WebviewWidget children (possibly empty) of this widget
+    # An array of Webview::Drawable children (possibly empty) of this drawable
     attr_reader :children
 
-    # Set instance variables for the display properties of this widget. Bind Shoes
-    # events for changes of parent widget and changes of property values.
+    # Set instance variables for the Shoes styles of this drawable. Bind Shoes
+    # events for changes of parent drawable and changes of property values.
     def initialize(properties)
-      log_init("WV::Widget")
+      log_init("Webview::Drawable")
+
+      @shoes_style_names = properties.keys.map(&:to_s) - ["shoes_linkable_id"]
 
       # Call method, which looks up the parent
       @shoes_linkable_id = properties["shoes_linkable_id"] || properties[:shoes_linkable_id]
       unless @shoes_linkable_id
-        raise "Could not find property shoes_linkable_id in #{properties.inspect}!"
+        raise Scarpe::MissingAttributeError, "Could not find property shoes_linkable_id in #{properties.inspect}!"
       end
 
-      # Set the display properties
+      # Set the Shoes styles as instance variables
       properties.each do |k, v|
         next if k == "shoes_linkable_id"
 
         instance_variable_set("@" + k.to_s, v)
       end
 
-      # The parent field is *almost* simple enough that a typed display property would handle it.
+      # Must call this before bind
+      super(linkable_id: @shoes_linkable_id)
+
       bind_shoes_event(event_name: "parent", target: shoes_linkable_id) do |new_parent_id|
-        display_parent = WebviewDisplayService.instance.query_display_widget_for(new_parent_id)
+        display_parent = DisplayService.instance.query_display_drawable_for(new_parent_id)
         if @parent != display_parent
           set_parent(display_parent)
         end
       end
 
-      # When Shoes widgets change properties, we get a change notification here
+      # When Shoes drawables change properties, we get a change notification here
       bind_shoes_event(event_name: "prop_change", target: shoes_linkable_id) do |prop_changes|
         prop_changes.each do |k, v|
           instance_variable_set("@" + k, v)
@@ -71,19 +76,25 @@ class Scarpe
       bind_shoes_event(event_name: "destroy", target: shoes_linkable_id) do
         destroy_self
       end
+    end
 
-      super(linkable_id: @shoes_linkable_id)
+    def shoes_styles
+      p = {}
+      @shoes_style_names.each do |prop_name|
+        p[prop_name] = instance_variable_get("@#{prop_name}")
+      end
+      p
     end
 
     # Properties_changed will be called automatically when properties change.
-    # The widget should delete any changes from the Hash that it knows how
+    # The drawable should delete any changes from the Hash that it knows how
     # to incrementally handle, and pass the rest to super. If any changes
     # go entirely un-handled, a full redraw will be scheduled.
     # This exists to be overridden by children watching for changes.
     #
     # @param changes [Hash] a Hash of new values for properties that have changed
     def properties_changed(changes)
-      # If a widget does something really nonstandard with its html_id or element, it will
+      # If a drawable does something really nonstandard with its html_id or element, it will
       # need to override to prevent this from happening. That's easy enough, though.
       if changes.key?("hidden")
         hidden = changes.delete("hidden")
@@ -99,7 +110,7 @@ class Scarpe
       needs_update! unless changes.empty?
     end
 
-    # Give this widget a new parent, including managing the appropriate child lists for parent widgets.
+    # Give this drawable a new parent, including managing the appropriate child lists for parent drawables.
     def set_parent(new_parent)
       @parent&.remove_child(self)
       new_parent&.add_child(self)
@@ -108,7 +119,7 @@ class Scarpe
 
     # A shorter inspect text for prettier irb output
     def inspect
-      "#<#{self.class}:#{self.object_id} @shoes_linkable_id=#{@shoes_linkable_id} @parent=#{@parent.inspect} @children=#{@children.inspect}>"
+      "#<#{self.class}:#{self.object_id} @shoes_linkable_id=#{@shoes_linkable_id} @children=#{@children.inspect}>"
     end
 
     protected
@@ -169,18 +180,22 @@ class Scarpe
 
     public
 
-    # This gets a mini-webview for just this element and its children, if any.
-    # It is normally called by the widget itself to do its DOM management.
+    # This gets an accessor for just this element's HTML ID.
+    # It is normally called by the drawable itself to do its DOM management.
+    # Drawables are required to use their html_id for their outermost element,
+    # to make sure that remove(), hidden() etc. affect every part of the drawable.
     #
     # @return [Scarpe::WebWrangler::ElementWrangler] a DOM object manager
     def html_element
-      @elt_wrangler ||= Scarpe::WebWrangler::ElementWrangler.new(html_id)
+      @elt_wrangler ||= Scarpe::Webview::WebWrangler::ElementWrangler.new(html_id)
     end
 
     # Return a promise that guarantees all currently-requested changes have completed
     #
     # @return [Scarpe::Promise] a promise that will be fulfilled when all pending changes have finished
     def promise_update
+      # Doesn't matter what ElementWrangler we use -- they all return an update promise
+      # that includes all pending updates, no matter who they're for.
       html_element.promise_update
     end
 
@@ -188,7 +203,7 @@ class Scarpe
     #
     # @return [String] the HTML ID
     def html_id
-      object_id.to_s
+      @linkable_id.to_s
     end
 
     # to_html is intended to get the HTML DOM rendering of this object and its children.
@@ -198,50 +213,58 @@ class Scarpe
     def to_html
       @children ||= []
       child_markup = @children.map(&:to_html).join
-      if respond_to?(:element)
-        element { child_markup }
-      else
-        child_markup
-      end
+      element { child_markup }
     end
 
     # This binds a Scarpe JS callback, handled via a single dispatch point in the app
     #
-    # @param event [String] the Scarpe widget event name
+    # @param event [String] the Scarpe drawable event name
     # @yield the block to call when the event occurs
     def bind(event, &block)
-      raise("Widget has no linkable_id! #{inspect}") unless linkable_id
+      raise(Scarpe::MissingAttributeError, "Drawable has no linkable_id! #{inspect}") unless linkable_id
 
-      WebviewDisplayService.instance.app.bind("#{linkable_id}-#{event}", &block)
+      DisplayService.instance.app.bind("#{linkable_id}-#{event}", &block)
     end
 
-    # Removes the element from both the Ruby Widget tree and the HTML DOM.
+    # Removes the element from both the Ruby Drawable tree and the HTML DOM.
+    # Unsubscribe from all Shoes events.
     # Return a promise for when that HTML change will be visible.
     #
     # @return [Scarpe::Promise] a promise that is fulfilled when the HTML change is complete
     def destroy_self
       @parent&.remove_child(self)
+      unsub_all_shoes_events
       html_element.remove
     end
 
-    # Request a full redraw of all widgets.
+    # Request a full redraw of the entire window, including the entire tree of
+    # drawables and the outer "empty page" frame.
+    #
+    # @return [void]
+    def full_window_redraw!
+      DisplayService.instance.app.request_redraw!
+    end
+
+    # Request a full redraw of this drawable, including all its children.
+    # Can be overridden in drawable subclasses if needed. An override would normally
+    # only be needed if re-rendering the element with the given html_id
+    # wasn't enough (and then remove would also need to be overridden.)
     #
-    # It's really hard to do dirty-tracking here because the redraws are fully asynchronous.
-    # And so we can't easily cancel one "in flight," and we can't easily pick up the latest
-    # changes... And we probably don't want to, because we may be halfway through a batch.
+    # This occurs by default if a property is changed and the drawable
+    # doesn't remove its change in property_changed.
     #
     # @return [void]
     def needs_update!
-      WebviewDisplayService.instance.app.request_redraw!
+      html_element.outer_html = to_html
     end
 
-    # Generate JS code to trigger a specific event name on this widget with the supplies arguments.
+    # Generate JS code to trigger a specific event name on this drawable with the supplies arguments.
     #
     # @param handler_function_name [String] the event name - @see #bind
     # @param args [Array] additional arguments that will be passed to the event in the generated JS
     # @return [String] the generated JS code
     def handler_js_code(handler_function_name, *args)
-      raise("Widget has no linkable_id! #{inspect}") unless linkable_id
+      raise(Scarpe::MissingAttributeError, "Drawable has no linkable_id! #{inspect}") unless linkable_id
 
       js_args = ["'#{linkable_id}-#{handler_function_name}'", *args].join(", ")
       "scarpeHandler(#{js_args})"