clogs 0.1.0

data/lib/clogs/paragraph.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require_relative "text"
+
+module Clogs
+  # Word-level text layout.
+  #
+  # libui will happily wrap a whole attributed string for us, but it will not
+  # tell us *where* it put anything -- there is no hit-testing or caret API on
+  # uiDrawTextLayout. Shoes needs that geometry: links have to be clickable,
+  # `para#hit` has to map a pixel to a character, and the editor has to draw a
+  # caret.
+  #
+  # So Clogs does its own line breaking. Each run is split into words, each
+  # word is measured once and cached, and lines are filled greedily. Drawing
+  # then batches adjacent words that share a style back into a single layout,
+  # so the common case still costs one libui text layout per line per style.
+  class Paragraph
+    # Shoes' named sizes, matching Scarpe's.
+    SIZES = {
+      inscription: 10, ins: 10, para: 12, caption: 14,
+      tagline: 18, subtitle: 26, title: 34, banner: 48
+    }.freeze
+
+    Placed = Struct.new(:text, :style, :x, :y, :width, :height, :owner, :char_offset)
+
+    attr_reader :width, :height, :lines, :placed
+
+    class << self
+      # Cache of [style_key, text] => [width, height]. Text-heavy apps repeat
+      # the same words constantly, and each miss costs an attributed string,
+      # a text layout and two FFI calls.
+      def measure_cache
+        @measure_cache ||= {}
+      end
+
+      def measure(text, style)
+        return [0.0, line_height(style)] if text.empty?
+
+        key = [style.cache_key, text].freeze
+        measure_cache[key] ||= begin
+          block = TextBlock.new(
+            [Run.new(text: text, size: style.size, family: style.family,
+              bold: style.bold, italic: style.italic, color: style.color)],
+            -1,
+            default_family: style.family,
+            default_size: style.size
+          )
+          dims = [block.width, block.height]
+          block.free
+          dims
+        end
+      end
+
+      def line_height(style)
+        key = [style.cache_key, :__line_height].freeze
+        measure_cache[key] ||= begin
+          w, h = measure("Hg", style)
+          _ = w
+          [0.0, h]
+        end
+        measure_cache[key][1]
+      end
+    end
+
+    # An immutable text style. Runs with equal styles can be drawn together.
+    TextStyle = Struct.new(:family, :size, :bold, :italic, :underline, :color, :bg, :owner, keyword_init: true) do
+      def cache_key
+        @cache_key ||= [family, size, bold, italic].freeze
+      end
+
+      def with(**changes)
+        TextStyle.new(to_h.merge(changes))
+      end
+
+      def same_run_as?(other)
+        family == other.family && size == other.size && bold == other.bold &&
+          italic == other.italic && underline == other.underline && color == other.color
+      end
+    end
+
+    # @param runs [Array<Array(String, TextStyle)>] text and its style
+    # @param wrap_width [Numeric] width to wrap at
+    def initialize(runs, wrap_width, align: :left)
+      @runs = runs
+      @wrap_width = wrap_width.to_f
+      @align = align
+      layout
+    end
+
+    # Split into words while keeping the whitespace attached to the preceding
+    # word, so that trailing spaces do not start a new line on their own.
+    def self.tokenize(text)
+      text.scan(/\n|[^\s]+[ \t]*|[ \t]+/)
+    end
+
+    def layout
+      @placed = []
+      x = 0.0
+      y = 0.0
+      line_start = 0
+      line_height = 0.0
+      char_offset = 0
+      max_x = 0.0
+
+      flush_line = lambda do
+        align_line(line_start, x, line_height)
+        max_x = [max_x, x].max
+        y += line_height.positive? ? line_height : 0
+        x = 0.0
+        line_height = 0.0
+        line_start = @placed.size
+      end
+
+      @runs.each do |text, style|
+        self.class.tokenize(text.to_s).each do |token|
+          if token == "\n"
+            line_height = self.class.line_height(style) if line_height.zero?
+            char_offset += 1
+            flush_line.call
+            next
+          end
+
+          w, h = self.class.measure(token, style)
+          # Trailing spaces should not force a wrap.
+          stripped = token.rstrip
+          effective_w = stripped == token ? w : self.class.measure(stripped, style)[0]
+
+          if x.positive? && @wrap_width.positive? && x + effective_w > @wrap_width
+            flush_line.call
+          end
+
+          @placed << Placed.new(token, style, x, y, w, h, style.owner, char_offset)
+          char_offset += token.length
+          x += w
+          line_height = [line_height, h].max
+        end
+      end
+      flush_line.call
+
+      @width = max_x
+      @height = y
+    end
+
+    def align_line(from, line_width, _line_height)
+      return if @align == :left || @wrap_width <= 0
+
+      shift = case @align
+      when :center then (@wrap_width - line_width) / 2.0
+      when :right then @wrap_width - line_width
+      else 0.0
+      end
+      return if shift <= 0
+
+      (from...@placed.size).each { |i| @placed[i].x += shift }
+    end
+
+    # Draw, batching runs that share a line and a style.
+    def draw(painter, ox, oy)
+      batch = []
+      flush = lambda do
+        next if batch.empty?
+
+        first = batch.first
+        text = batch.map(&:text).join
+        style = first.style
+        block = TextBlock.new(
+          [Run.new(text: text, size: style.size, family: style.family, bold: style.bold,
+            italic: style.italic, underline: style.underline, color: style.color)],
+          -1,
+          default_family: style.family,
+          default_size: style.size
+        )
+        if style.bg
+          h = batch.map(&:height).max
+          w = batch.sum(&:width)
+          painter.fill_rect(ox + first.x, oy + first.y, w, h, style.bg)
+        end
+        block.draw(painter, ox + first.x, oy + first.y)
+        block.free
+        batch = []
+      end
+
+      @placed.each do |item|
+        prev = batch.last
+        if prev && (prev.y != item.y || !prev.style.same_run_as?(item.style) ||
+            prev.style.bg != item.style.bg)
+          flush.call
+        end
+        batch << item
+      end
+      flush.call
+    end
+
+    # Bounding boxes for everything contributed by `owner`, used to make links
+    # clickable. One box per line the owner appears on.
+    def boxes_for(owner)
+      items = @placed.select { |i| i.owner.equal?(owner) }
+      items.group_by(&:y).map do |y, line_items|
+        x0 = line_items.map(&:x).min
+        x1 = line_items.map { |i| i.x + i.width }.max
+        h = line_items.map(&:height).max
+        [x0, y, x1 - x0, h]
+      end
+    end
+
+    # Character index nearest to a point, for text selection.
+    def index_at(px, py)
+      line = @placed.select { |i| py >= i.y && py < i.y + i.height }
+      line = @placed if line.empty?
+      return 0 if line.empty?
+
+      item = line.find { |i| px < i.x + i.width } || line.last
+      frac = item.width.zero? ? 0 : (px - item.x) / item.width
+      item.char_offset + (frac * item.text.length).round.clamp(0, item.text.length)
+    end
+  end
+end

data/lib/clogs/style.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Clogs
+  # Coercion of Shoes style values into the numbers and colours the painter
+  # wants. Shoes is famously relaxed about types: a width can be `100`, `0.5`,
+  # `"50%"` or `-20`, and a colour can be a symbol, a string, an array or a
+  # Shoes::Color.
+  module Style
+    module_function
+
+    # Resolve a Shoes dimension against the space available.
+    #
+    #   100    => 100 pixels
+    #   0.5    => half of `available`
+    #   "50%"  => half of `available`
+    #   -20    => `available` minus 20
+    #   nil    => nil (meaning "size yourself")
+    def dimension(value, available)
+      case value
+      when nil then nil
+      when Integer
+        value.negative? ? [available + value, 0].max : value
+      when Float
+        value <= 1.0 && value >= -1.0 ? (available * value).round : value.round
+      when String
+        if value.end_with?("%")
+          (available * value.to_f / 100.0).round
+        else
+          value.to_i
+        end
+      else
+        value.respond_to?(:to_i) ? value.to_i : nil
+      end
+    end
+
+    # Shoes colours reach the display service as [r, g, b, a] arrays, but user
+    # code can also set a bare symbol or "#ff0000" that never went through
+    # Shoes::Colors.
+    def color(value, default = nil)
+      case value
+      when nil then default
+      when Array
+        # Shoes accepts both 0-255 integers and 0.0-1.0 floats, and mixes them
+        # freely: `black(0.6)` is [0, 0, 0, 0.6].
+        r, g, b, a = value
+        [channel(r), channel(g), channel(b), a.nil? ? 255 : channel(a)]
+      when String
+        if value.start_with?("#")
+          hex(value)
+        else
+          named(value) || default
+        end
+      when Symbol
+        named(value.to_s) || default
+      else
+        if value.respond_to?(:to_a)
+          color(value.to_a, default)
+        else
+          default
+        end
+      end
+    end
+
+    # One colour channel, from either convention.
+    def channel(value)
+      return 0 if value.nil?
+      return (value.clamp(0.0, 1.0) * 255).round if value.is_a?(Float) && value <= 1.0
+
+      value.to_i.clamp(0, 255)
+    end
+
+    def hex(str)
+      s = str.delete_prefix("#")
+      s = s.chars.map { |c| c * 2 }.join if s.length == 3
+      alpha = s[6, 2]
+      [s[0, 2].to_i(16), s[2, 2].to_i(16), s[4, 2].to_i(16),
+       alpha.nil? || alpha.empty? ? 255 : alpha.to_i(16)]
+    end
+
+    def named(name)
+      require "shoes/colors" if !defined?(Shoes::Colors)
+      rgb = Shoes::Colors.to_rgb(name.to_sym)
+      rgb.is_a?(Array) ? color(rgb) : nil
+    rescue StandardError
+      nil
+    end
+
+    # Shoes lets a margin be one number or [left, top, right, bottom].
+    def margins(styles)
+      m = styles["margin"] || styles[:margin]
+      base = case m
+      when nil then [0, 0, 0, 0]
+      when Array then m.map(&:to_i)
+      when Numeric then [m.to_i] * 4
+      when String then [m.to_i] * 4
+      else [0, 0, 0, 0]
+      end
+      left, top, right, bottom = base
+      [
+        (styles["margin_left"] || left).to_i,
+        (styles["margin_top"] || top).to_i,
+        (styles["margin_right"] || right).to_i,
+        (styles["margin_bottom"] || bottom).to_i
+      ]
+    end
+
+    def paddings(styles)
+      p = styles["padding"] || styles[:padding]
+      base = case p
+      when nil then [0, 0, 0, 0]
+      when Array then p.map(&:to_i)
+      when Numeric then [p.to_i] * 4
+      else [0, 0, 0, 0]
+      end
+      left, top, right, bottom = base
+      [
+        (styles["padding_left"] || left).to_i,
+        (styles["padding_top"] || top).to_i,
+        (styles["padding_right"] || right).to_i,
+        (styles["padding_bottom"] || bottom).to_i
+      ]
+    end
+  end
+end

data/lib/clogs/text.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative "ui"
+
+module Clogs
+  # One styled run of text inside a paragraph.
+  Run = Struct.new(:text, :size, :color, :family, :bold, :italic, :underline, :owner, keyword_init: true) do
+    def style_key
+      [size, color, family, bold, italic, underline]
+    end
+  end
+
+  # A laid-out paragraph.
+  #
+  # libui gives us Pango/DirectWrite/Core Text via uiDrawTextLayout: an
+  # attributed string plus a wrap width, and it reports the resulting extents.
+  # That covers Shoes' text model (a paragraph of differently-styled spans that
+  # wraps) without us writing a line breaker.
+  #
+  # What it does *not* give us is per-character hit testing or caret geometry,
+  # which is why Clogs' own text editing (edit_line / edit_box) measures
+  # substrings instead of asking the layout where a click landed.
+  class TextBlock
+    ALIGN_LEFT = 0
+    ALIGN_CENTER = 1
+    ALIGN_RIGHT = 2
+
+    attr_reader :width, :height, :runs
+
+    def initialize(runs, wrap_width, align: ALIGN_LEFT, default_family: nil, default_size: nil)
+      @runs = runs
+      @wrap_width = wrap_width.to_f
+      @align = align
+      @default_family = default_family || Clogs.default_font_family
+      @default_size = default_size || Clogs.default_font_size
+      build
+    end
+
+    def draw(painter, x, y)
+      painter.draw_text(@layout, x, y)
+    end
+
+    # Width of the first `n` characters, used to place text carets.
+    def prefix_width(n)
+      return 0.0 if n <= 0
+
+      text = plain_text
+      n = text.length if n > text.length
+      @prefix_cache ||= {}
+      @prefix_cache[n] ||= begin
+        sub = TextBlock.new(
+          [Run.new(text: text[0, n], **first_style)],
+          -1,
+          default_family: @default_family,
+          default_size: @default_size
+        )
+        w = sub.width
+        sub.free
+        w
+      end
+    end
+
+    def plain_text
+      @plain_text ||= @runs.map { |r| r.text.to_s }.join
+    end
+
+    def free
+      UI::L.draw_free_text_layout(@layout) if @layout
+      UI::L.free_attributed_string(@astr) if @astr
+      @layout = nil
+      @astr = nil
+    end
+
+    private
+
+    def first_style
+      r = @runs.first
+      return { size: @default_size, color: [0, 0, 0, 255] } unless r
+
+      { size: r.size, color: r.color, family: r.family, bold: r.bold, italic: r.italic }
+    end
+
+    def build
+      @astr = UI::L.new_attributed_string("")
+      @runs.each do |run|
+        text = run.text.to_s
+        next if text.empty?
+
+        start = UI::L.attributed_string_len(@astr)
+        UI::L.attributed_string_append_unattributed(@astr, text)
+        finish = start + text.bytesize
+
+        if run.size
+          UI::L.attributed_string_set_attribute(@astr, UI::L.new_size_attribute(run.size.to_f), start, finish)
+        end
+        if run.color
+          r, g, b, a = run.color
+          UI::L.attributed_string_set_attribute(
+            @astr,
+            UI::L.new_color_attribute(r / 255.0, g / 255.0, b / 255.0, (a || 255) / 255.0),
+            start, finish
+          )
+        end
+        if run.family
+          UI::L.attributed_string_set_attribute(@astr, UI::L.new_family_attribute(run.family), start, finish)
+        end
+        if run.bold
+          UI::L.attributed_string_set_attribute(@astr, UI::L.new_weight_attribute(UI::WEIGHT_BOLD), start, finish)
+        end
+        if run.italic
+          UI::L.attributed_string_set_attribute(@astr, UI::L.new_italic_attribute(UI::ITALIC_ITALIC), start, finish)
+        end
+        if run.underline
+          UI::L.attributed_string_set_attribute(@astr, UI::L.new_underline_attribute(1), start, finish)
+        end
+      end
+
+      font = UI.font_descriptor(@default_family, @default_size)
+      params = UI.malloc(UI::L::FFI::DrawTextLayoutParams)
+      params.String = @astr
+      params.DefaultFont = font.to_ptr
+      # A negative width means "do not wrap"; libui wants a very large number.
+      params.Width = @wrap_width.negative? ? 1_000_000.0 : @wrap_width
+      params.Align = @align
+      # Keep the descriptor alive for as long as the layout uses it.
+      @font = font
+
+      @layout = UI::L.draw_new_text_layout(params)
+      @width, @height = UI.text_extents(@layout)
+    end
+  end
+end

data/lib/clogs/ui.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "libui"
+
+module Clogs
+  # Thin, hand-rolled conveniences over the raw libui FFI bindings.
+  #
+  # Two things make raw libui painful from Ruby and both are handled here:
+  #
+  # 1. Every callback handed to C must be a Fiddle::Closure that outlives the
+  #    C-side registration. Ruby will happily collect one that is still
+  #    installed, and libui will then jump into freed memory. {UI.callback}
+  #    keeps a permanent reference.
+  # 2. Structs must be malloc'd and marked with a free function, and several of
+  #    them (brushes, stroke params, font descriptors) are needed on every
+  #    single paint. Allocating them per-paint is measurable, so the hot ones
+  #    are pooled.
+  module UI
+    L = ::LibUI
+
+    # Fill modes
+    WINDING = 0
+    ALTERNATE = 1
+
+    # Line caps / joins
+    CAP_FLAT = 0
+    CAP_ROUND = 1
+    CAP_SQUARE = 2
+    JOIN_MITER = 0
+    JOIN_ROUND = 1
+    JOIN_BEVEL = 2
+
+    BRUSH_SOLID = 0
+    BRUSH_LINEAR_GRADIENT = 1
+    BRUSH_RADIAL_GRADIENT = 2
+
+    # Text weights/italics/stretches we actually use
+    WEIGHT_NORMAL = 400
+    WEIGHT_BOLD = 700
+    ITALIC_NORMAL = 0
+    ITALIC_ITALIC = 1
+    STRETCH_NORMAL = 4
+
+    # uiExtKey values, from ui.h. libui reports these separately from `Key`.
+    EXT_KEYS = {
+      1 => :escape, 2 => :insert, 3 => :delete, 4 => :home, 5 => :end,
+      6 => :page_up, 7 => :page_down, 8 => :up, 9 => :down, 10 => :left,
+      11 => :right, 12 => :f1, 13 => :f2, 14 => :f3, 15 => :f4, 16 => :f5,
+      17 => :f6, 18 => :f7, 19 => :f8, 20 => :f9, 21 => :f10, 22 => :f11,
+      23 => :f12
+    }.freeze
+
+    MOD_CTRL = 1 << 0
+    MOD_ALT = 1 << 1
+    MOD_SHIFT = 1 << 2
+    MOD_SUPER = 1 << 3
+
+    class << self
+      # Closures handed to C live forever. There are a bounded number of them
+      # (a handful per window plus one per timer) so this does not grow without
+      # bound in practice.
+      def callback(return_type, arg_types, &block)
+        closure = Fiddle::Closure::BlockCaller.new(return_type, arg_types, &block)
+        (@callbacks ||= []) << closure
+        closure
+      end
+
+      def malloc(struct_class)
+        s = struct_class.malloc
+        s.to_ptr.free = Fiddle::RUBY_FREE
+        s
+      end
+
+      # A solid uiDrawBrush. Colors arrive as Shoes [r, g, b, a] 0-255 arrays.
+      def solid_brush(color)
+        b = malloc(L::FFI::DrawBrush)
+        b.Type = BRUSH_SOLID
+        r, g, bl, a = color
+        b.R = r / 255.0
+        b.G = g / 255.0
+        b.B = bl / 255.0
+        b.A = (a || 255) / 255.0
+        b
+      end
+
+      # A linear or radial gradient brush. `stops` is [[pos, [r,g,b,a]], ...].
+      #
+      # The Stops array must stay alive as long as the brush does, so it is
+      # stashed on the brush object; Ruby's GC then keeps them together.
+      def gradient_brush(type, from, to, stops, outer_radius: 0)
+        b = malloc(L::FFI::DrawBrush)
+        b.Type = type
+        b.X0, b.Y0 = from
+        b.X1, b.Y1 = to
+        b.OuterRadius = outer_radius
+
+        buf = Fiddle::Pointer.malloc(stops.size * 40, Fiddle::RUBY_FREE)
+        stops.each_with_index do |(pos, color), i|
+          r, g, bl, a = color
+          buf[i * 40, 40] = [pos, r / 255.0, g / 255.0, bl / 255.0, (a || 255) / 255.0].pack("d5")
+        end
+        b.Stops = buf
+        b.NumStops = stops.size
+        b.instance_variable_set(:@clogs_stops, buf)
+        b
+      end
+
+      def stroke_params(thickness, cap: CAP_FLAT, join: JOIN_MITER, dashes: nil)
+        sp = malloc(L::FFI::DrawStrokeParams)
+        sp.Cap = cap
+        sp.Join = join
+        sp.Thickness = thickness.to_f
+        sp.MiterLimit = 10.0
+        if dashes && !dashes.empty?
+          buf = Fiddle::Pointer.malloc(dashes.size * 8, Fiddle::RUBY_FREE)
+          buf[0, dashes.size * 8] = dashes.map(&:to_f).pack("d*")
+          sp.Dashes = buf
+          sp.NumDashes = dashes.size
+          sp.instance_variable_set(:@clogs_dashes, buf)
+        else
+          sp.NumDashes = 0
+        end
+        sp.DashPhase = 0.0
+        sp
+      end
+
+      def font_descriptor(family, size, weight: WEIGHT_NORMAL, italic: ITALIC_NORMAL)
+        fd = malloc(L::FFI::FontDescriptor)
+        fd.Family = family
+        fd.Size = size.to_f
+        fd.Weight = weight
+        fd.Italic = italic
+        fd.Stretch = STRETCH_NORMAL
+        # Fiddle copies the string into the struct but does not own it; keep the
+        # Ruby string alive so the char* stays valid.
+        fd.instance_variable_set(:@clogs_family, family)
+        fd
+      end
+
+      # uiDrawTextLayoutExtents writes through two double pointers.
+      def text_extents(layout)
+        w = Fiddle::Pointer.malloc(8, Fiddle::RUBY_FREE)
+        h = Fiddle::Pointer.malloc(8, Fiddle::RUBY_FREE)
+        L.draw_text_layout_extents(layout, w, h)
+        [w[0, 8].unpack1("d"), h[0, 8].unpack1("d")]
+      end
+
+      # True if this libui build can blit a uiImage into a draw context.
+      # Stock libui-ng cannot; see docs/libui_shoes_coverage.md.
+      def draw_image?
+        return @draw_image unless @draw_image.nil?
+
+        @draw_image = L.respond_to?(:draw_image)
+      end
+    end
+  end
+end

data/lib/clogs/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Clogs
+  VERSION = "0.1.0"
+end