teek 0.1.0

data/sample/goldberg_helpers.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+# Canvas and Tcl helpers for the Goldberg demo.
+# Provides a thin wrapper around Tcl canvas commands so the draw/move
+# methods read almost like the original tk-ng version.
+#
+# Including class must provide:
+#   @app    - Teek::App instance
+#   @canvas - Tcl path of the canvas widget (String)
+
+module GoldbergHelpers
+
+  # -- Tcl value formatting ------------------------------------------------
+
+  def tcl_val(v)
+    case v
+    when true  then '1'
+    when false then '0'
+    when nil   then '{}'
+    when Symbol then v.to_s
+    when Array
+      inner = v.map { |e|
+        s = e.is_a?(Symbol) ? e.to_s : e.to_s
+        s.include?(' ') ? "{#{s}}" : s
+      }.join(' ')
+      "{#{inner}}"
+    when String
+      v.empty? ? '{}' : "{#{v}}"
+    when Numeric
+      v.to_s
+    else
+      "{#{v}}"
+    end
+  end
+
+  def format_font(f)
+    return "{#{f}}" if f.is_a?(String)
+    parts = f.map { |p|
+      s = p.is_a?(Symbol) ? p.to_s : p.to_s
+      s.include?(' ') ? "{#{s}}" : s
+    }
+    "{#{parts.join(' ')}}"
+  end
+
+  def tcl_opts(opts)
+    opts.map { |k, v|
+      key = k == :tag ? :tags : k
+      val = key == :font ? format_font(v) : tcl_val(v)
+      "-#{key} #{val}"
+    }.join(' ')
+  end
+
+  # -- Canvas item creation ------------------------------------------------
+  # All return the Tcl item id (string).
+
+  def ccreate(type, *coords, **opts)
+    c = coords.flatten.join(' ')
+    o = opts.empty? ? '' : " #{tcl_opts(opts)}"
+    @app.tcl_eval("#{@canvas} create #{type} #{c}#{o}")
+  end
+
+  def cline(*coords, **opts)   = ccreate(:line, *coords, **opts)
+  def cpoly(*coords, **opts)   = ccreate(:polygon, *coords, **opts)
+  def coval(*coords, **opts)   = ccreate(:oval, *coords, **opts)
+  def carc(*coords, **opts)    = ccreate(:arc, *coords, **opts)
+  def crect(*coords, **opts)   = ccreate(:rectangle, *coords, **opts)
+  def ctext(*coords, **opts)   = ccreate(:text, *coords, **opts)
+  def cbitmap(*coords, **opts) = ccreate(:bitmap, *coords, **opts)
+
+  # -- Canvas operations ---------------------------------------------------
+
+  def cmove(tag, dx, dy)
+    @app.tcl_eval("#{@canvas} move #{tag} #{dx} #{dy}")
+  end
+
+  def ccoords(tag, new_coords = nil)
+    if new_coords
+      @app.tcl_eval("#{@canvas} coords #{tag} #{new_coords.flatten.join(' ')}")
+    else
+      @app.tcl_eval("#{@canvas} coords #{tag}").split.map(&:to_f)
+    end
+  end
+
+  def cdel(*tags)
+    tags.each { |t| @app.tcl_eval("#{@canvas} delete #{t}") }
+  end
+
+  def cbbox(tag)
+    r = @app.tcl_eval("#{@canvas} bbox #{tag}")
+    r.empty? ? nil : r.split.map(&:to_f)
+  end
+
+  def cscale(tag, ox, oy, sx, sy)
+    @app.tcl_eval("#{@canvas} scale #{tag} #{ox} #{oy} #{sx} #{sy}")
+  end
+
+  def citemconfig(tag, **opts)
+    @app.tcl_eval("#{@canvas} itemconfigure #{tag} #{tcl_opts(opts)}")
+  end
+
+  def citemcget(tag, opt)
+    @app.tcl_eval("#{@canvas} itemcget #{tag} -#{opt}")
+  end
+
+  def cfind(tag)
+    r = @app.tcl_eval("#{@canvas} find withtag #{tag}")
+    r.empty? ? [] : r.split
+  end
+
+  def craise(tag, above = nil)
+    cmd = "#{@canvas} raise #{tag}"
+    cmd += " #{above}" if above
+    @app.tcl_eval(cmd)
+  end
+
+  def clower(tag, below = nil)
+    cmd = "#{@canvas} lower #{tag}"
+    cmd += " #{below}" if below
+    @app.tcl_eval(cmd)
+  end
+
+  # Bind an event on a canvas item (tag).
+  def cbind_item(tag, event, &block)
+    id = @app.register_callback(proc { |*| block.call })
+    @app.tcl_eval("#{@canvas} bind #{tag} <#{event}> {ruby_callback #{id}}")
+  end
+
+  # Bind an event on the canvas widget itself.
+  def canvas_bind(event, &block)
+    @app.bind(@canvas, event, &block)
+  end
+
+  def canvas_bind_remove(event)
+    @app.unbind(@canvas, event)
+  end
+
+  # -- Misc helpers --------------------------------------------------------
+
+  def winfo_pixels(val)
+    @app.tcl_eval("winfo pixels #{@canvas} #{val}").to_i
+  end
+
+  def clock_ms
+    (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i
+  end
+
+  # Simple wrapper for a Tcl variable (for -textvariable / -variable binding).
+  class TclVar
+    attr_reader :name
+
+    def initialize(app, var_name, initial = '')
+      @app = app
+      @name = "::gb_#{var_name}"
+      set(initial)
+    end
+
+    def get
+      @app.get_variable(@name)
+    end
+
+    def set(v)
+      @app.set_variable(@name, v)
+    end
+
+    def to_s = get
+    def to_i = get.to_i
+    def to_f = get.to_f
+    def bool = (get != '0' && !get.empty?)
+  end
+end

data/sample/minesweeper/minesweeper.rb

@@ -0,0 +1,452 @@
+# frozen_string_literal: true
+#
+# Minesweeper clone built with Teek.
+#
+# Demonstrates:
+#   - Loading and resizing PNG images with Tk's photo system
+#   - Canvas-based game grid using image items
+#   - Click handling via canvas coordinate math (not per-item bindings)
+#   - Tcl variables for live-updating labels (-textvariable)
+#   - Menus with radiobuttons and keyboard accelerators
+#   - Scheduling repeated work with app.after
+#   - register_callback to bridge Ruby procs into Tcl event handlers
+#
+# Tile artwork: "Minesweeper Tile Set" by eugeneloza (CC0)
+# https://opengameart.org/content/minesweeper-tile-set
+
+require_relative '../../lib/teek'
+
+class Minesweeper
+  # The source PNGs are 216x216. Tk can shrink them with "copy -subsample N N"
+  # which keeps every Nth pixel. 216 / 6 = 36, giving us nice 36px tiles.
+  TILE_SIZE = 36
+  SUBSAMPLE = 6
+
+  LEVELS = {
+    beginner:     { cols: 9,  rows: 9,  mines: 10 },
+    intermediate: { cols: 16, rows: 16, mines: 40 },
+    expert:       { cols: 30, rows: 16, mines: 99 }
+  }.freeze
+
+  def initialize(app, level: :beginner)
+    @app = app
+    @level = level
+    apply_level
+    load_images
+    build_ui
+    new_game
+  end
+
+  private
+
+  # -- Setup ---------------------------------------------------------------
+
+  def apply_level
+    cfg = LEVELS[@level]
+    @cols  = cfg[:cols]
+    @rows  = cfg[:rows]
+    @num_mines = cfg[:mines]
+  end
+
+  # Tk's "image create photo" loads a PNG into a named in-memory image.
+  # The full 216x216 images are too large for game tiles, so we create a
+  # second (empty) photo and copy into it with -subsample to shrink.
+  # After copying, we delete the full-size image to free memory.
+  #
+  # The resulting @img hash maps game state keys (:hidden, :flag, 1..8, etc.)
+  # to Tk photo names we can assign to canvas image items later.
+  def load_images
+    dir = File.join(__dir__, 'assets')
+    @img = {}
+
+    # Map game state keys to the PNG filename suffixes in assets/
+    tiles = { hidden: 'X', empty: '0', flag: 'F', mine: 'M' }
+    (1..8).each { |n| tiles[n] = n.to_s }
+
+    tiles.each do |key, suffix|
+      full  = "ms_full_#{suffix}"
+      small = "ms_#{suffix}"
+      path  = File.join(dir, "MINESWEEPER_#{suffix}.png")
+
+      # Load full-size PNG into a temporary Tk photo
+      @app.command(:image, :create, :photo, full, file: path)
+
+      # Create the smaller photo and copy with subsampling.
+      # -subsample takes two separate int args (x y), which command() can't
+      # express as a single kwarg, so this line stays as tcl_eval.
+      @app.command(:image, :create, :photo, small)
+      @app.tcl_eval("#{small} copy #{full} -subsample #{SUBSAMPLE} #{SUBSAMPLE}")
+
+      # Free the full-size image -- we only need the 36x36 version
+      @app.command(:image, :delete, full)
+      @img[key] = small
+    end
+  end
+
+  def build_ui
+    # "wm" commands control the window manager -- title, resizability, etc.
+    # "." is the root Tk window (every widget path starts from here).
+    @app.command(:wm, :title, '.', 'Minesweeper')
+    @app.command(:wm, :resizable, '.', 0, 0)
+
+    build_menu
+    build_header
+    build_canvas
+  end
+
+  # Tk menus: create a menu widget, attach it to the window with "configure
+  # -menu", then add items. Each item that triggers Ruby code needs a
+  # registered callback -- register_callback returns an integer ID, and
+  # "ruby_callback <id>" in Tcl invokes the corresponding Ruby proc.
+  def build_menu
+    @app.command(:menu, '.menubar')
+    @app.command('.', :configure, menu: '.menubar')
+    @app.command(:menu, '.menubar.game', tearoff: 0)
+    @app.command('.menubar', :add, :cascade, label: 'Game', menu: '.menubar.game')
+
+    # "add command" creates a clickable menu item.
+    # -accelerator is cosmetic (shows "F2" in the menu) -- the actual
+    # keybinding is set separately with "bind".
+    # With command(), procs are auto-registered as callbacks -- no need
+    # to manually call register_callback + interpolate the ID.
+    new_game_proc = proc { |*| new_game }
+    @app.command('.menubar.game', :add, :command,
+                 label: 'New Game', accelerator: 'F2', command: new_game_proc)
+    @app.command(:bind, '.', '<F2>', new_game_proc)
+
+    @app.command('.menubar.game', :add, :separator)
+
+    # "add radiobutton" items share a Tcl variable -- Tk automatically shows
+    # a bullet next to the selected one. The -variable points to a global
+    # Tcl variable (:: prefix), and -value is what gets stored when selected.
+    @level_var = '::ms_level'
+    @app.command(:set, @level_var, @level)
+    LEVELS.each_key do |lvl|
+      @app.command('.menubar.game', :add, :radiobutton,
+                   label: lvl.capitalize, variable: @level_var, value: lvl,
+                   command: proc { |*| change_level(lvl) })
+    end
+
+    @app.command('.menubar.game', :add, :separator)
+
+    @app.command('.menubar.game', :add, :command,
+                 label: 'Exit', command: proc { |*| @app.command(:destroy, '.') })
+  end
+
+  # The header bar uses "pack" geometry: mine counter on the left, face
+  # button expanding to fill the center, timer on the right.
+  #
+  # -textvariable connects a label to a Tcl variable. When we later do
+  # "set ::ms_mines 7", the label updates automatically -- no manual
+  # refresh needed. This is one of Tk's nicest features.
+  def build_header
+    @app.command(:frame, '.hdr', relief: :raised, bd: 2)
+    @app.command(:pack, '.hdr', fill: :x)
+
+    # Mine counter (left) -- red digits on black, like the classic LCD look
+    @mine_var = '::ms_mines'
+    @app.command(:set, @mine_var, @num_mines)
+    @app.command(:label, '.hdr.mines', textvariable: @mine_var, width: 4,
+                 font: 'TkFixedFont 14 bold', fg: :red, bg: :black,
+                 relief: :sunken, anchor: :center)
+    @app.command(:pack, '.hdr.mines', side: :left, padx: 5, pady: 3)
+
+    # Face button (center) -- doubles as new-game button
+    @face = '.hdr.face'
+    @app.command(:button, @face, text: ':)', width: 3,
+                 font: 'TkFixedFont 12 bold',
+                 command: proc { |*| new_game })
+    @app.command(:pack, @face, side: :left, expand: 1, padx: 5, pady: 3)
+
+    # Timer (right)
+    @time_var = '::ms_time'
+    @app.command(:set, @time_var, 0)
+    @app.command(:label, '.hdr.time', textvariable: @time_var, width: 4,
+                 font: 'TkFixedFont 14 bold', fg: :red, bg: :black,
+                 relief: :sunken, anchor: :center)
+    @app.command(:pack, '.hdr.time', side: :right, padx: 5, pady: 3)
+  end
+
+  # The game grid is a single Tk canvas filled with image items.
+  #
+  # Instead of binding a click handler to each of the 81+ cells (which would
+  # mean hundreds of registered callbacks), we bind ONE handler to the whole
+  # canvas. The trick: Tk's bind substitution "%x %y" gives us the pointer
+  # coordinates. We stash them in Tcl variables, then in the Ruby callback
+  # we read those variables and divide by TILE_SIZE to get row/col.
+  #
+  # "canvasx %x" converts window coords to canvas coords (matters if the
+  # canvas is scrolled, though we don't scroll here).
+  def build_canvas
+    cw = @cols * TILE_SIZE
+    ch = @rows * TILE_SIZE
+    @canvas = '.c'
+    @app.command(:canvas, @canvas, width: cw, height: ch, highlightthickness: 0)
+    @app.command(:pack, @canvas)
+
+    # Left-click: reveal a cell
+    lcb = @app.register_callback(proc { |*|
+      row, col = canvas_cell
+      on_left_click(row, col) if row
+    })
+    @app.tcl_eval("bind #{@canvas} <Button-1> " \
+                  "{set ::_ms_x [#{@canvas} canvasx %x]; " \
+                  "set ::_ms_y [#{@canvas} canvasy %y]; " \
+                  "ruby_callback #{lcb}}")
+
+    # Right-click: toggle flag. Binding all three events covers:
+    #   Button-2  -- right-click on macOS
+    #   Button-3  -- right-click on Linux/Windows
+    #   Ctrl+click -- fallback for single-button trackpads
+    rcb = @app.register_callback(proc { |*|
+      row, col = canvas_cell
+      on_right_click(row, col) if row
+    })
+    %w[Button-2 Button-3 Control-Button-1].each do |ev|
+      @app.tcl_eval("bind #{@canvas} <#{ev}> " \
+                    "{set ::_ms_x [#{@canvas} canvasx %x]; " \
+                    "set ::_ms_y [#{@canvas} canvasy %y]; " \
+                    "ruby_callback #{rcb}}")
+    end
+  end
+
+  # Read the stashed click coordinates and convert to grid position.
+  # Returns [row, col] or [nil, nil] if the click was outside the grid.
+  def canvas_cell
+    mx = @app.command(:set, '::_ms_x').to_f
+    my = @app.command(:set, '::_ms_y').to_f
+    col = (mx / TILE_SIZE).to_i
+    row = (my / TILE_SIZE).to_i
+    in_bounds?(row, col) ? [row, col] : [nil, nil]
+  end
+
+  # -- Game state ----------------------------------------------------------
+
+  def new_game
+    stop_timer
+    @game_over   = false
+    @first_click = true
+    @flags_placed = 0
+    @elapsed = 0
+
+    @mine     = Array.new(@rows) { Array.new(@cols, false) }
+    @revealed = Array.new(@rows) { Array.new(@cols, false) }
+    @flagged  = Array.new(@rows) { Array.new(@cols, false) }
+    @adjacent = Array.new(@rows) { Array.new(@cols, 0) }
+
+    # Update the header displays via their Tcl variables
+    @app.command(:set, @mine_var, @num_mines)
+    @app.command(:set, @time_var, 0)
+    @app.command(@face, :configure, text: ':)')
+
+    draw_board
+  end
+
+  # Changing difficulty resizes the canvas and resets. The window auto-shrinks
+  # because we set "wm resizable . 0 0" -- Tk recomputes the geometry.
+  def change_level(level)
+    return if level == @level
+
+    @level = level
+    apply_level
+
+    cw = @cols * TILE_SIZE
+    ch = @rows * TILE_SIZE
+    @app.command(@canvas, :configure, width: cw, height: ch)
+
+    new_game
+  end
+
+  # Populate the canvas with hidden-cell images. "canvas create image" places
+  # a Tk photo at (x, y) with -anchor nw (top-left corner). It returns a
+  # numeric item ID that we store in @cell_id so we can update each cell's
+  # image later with "itemconfigure <id> -image <photo>".
+  def draw_board
+    @app.command(@canvas, :delete, :all)
+    @cell_id = Array.new(@rows) { Array.new(@cols) }
+
+    @rows.times do |r|
+      @cols.times do |c|
+        x = c * TILE_SIZE
+        y = r * TILE_SIZE
+        @cell_id[r][c] = @app.command(@canvas, :create, :image, x, y,
+                                      image: @img[:hidden], anchor: :nw)
+      end
+    end
+  end
+
+  # -- Mine placement ------------------------------------------------------
+
+  # Mines are placed on the first click, not at game start. This guarantees
+  # the player's first click is always safe (and so are its neighbors).
+  def place_mines(safe_r, safe_c)
+    safe = { [safe_r, safe_c] => true }
+    neighbors(safe_r, safe_c).each { |nr, nc| safe[[nr, nc]] = true }
+
+    candidates = []
+    @rows.times { |r| @cols.times { |c| candidates << [r, c] unless safe[[r, c]] } }
+    candidates.shuffle!.first(@num_mines).each { |r, c| @mine[r][c] = true }
+
+    # Precompute how many mines neighbor each cell
+    @rows.times do |r|
+      @cols.times do |c|
+        next if @mine[r][c]
+        @adjacent[r][c] = neighbors(r, c).count { |nr, nc| @mine[nr][nc] }
+      end
+    end
+  end
+
+  # -- Click handlers ------------------------------------------------------
+
+  def on_left_click(r, c)
+    return if @game_over || @flagged[r][c] || @revealed[r][c]
+
+    if @first_click
+      @first_click = false
+      place_mines(r, c)
+      start_timer
+    end
+
+    if @mine[r][c]
+      game_over_lose(r, c)
+    else
+      reveal(r, c)
+      check_win
+    end
+  end
+
+  def on_right_click(r, c)
+    return if @game_over || @revealed[r][c]
+
+    if @flagged[r][c]
+      @flagged[r][c] = false
+      @flags_placed -= 1
+      set_cell_image(r, c, :hidden)
+    else
+      @flagged[r][c] = true
+      @flags_placed += 1
+      set_cell_image(r, c, :flag)
+    end
+    @app.command(:set, @mine_var, @num_mines - @flags_placed)
+  end
+
+  # -- Reveal / win / lose -------------------------------------------------
+
+  # Classic minesweeper flood fill: reveal a cell, and if it has zero
+  # adjacent mines, recursively reveal all its neighbors. This produces
+  # the satisfying "clearing" effect when you click an open area.
+  def reveal(r, c)
+    return unless in_bounds?(r, c)
+    return if @revealed[r][c] || @flagged[r][c] || @mine[r][c]
+
+    @revealed[r][c] = true
+    count = @adjacent[r][c]
+
+    if count == 0
+      set_cell_image(r, c, :empty)
+      neighbors(r, c).each { |nr, nc| reveal(nr, nc) }
+    else
+      set_cell_image(r, c, count)
+    end
+  end
+
+  # Win when every non-mine cell is revealed.
+  def check_win
+    unrevealed = 0
+    @rows.times { |r| @cols.times { |c| unrevealed += 1 unless @revealed[r][c] } }
+    return unless unrevealed == @num_mines
+
+    @game_over = true
+    stop_timer
+    @app.command(@face, :configure, text: 'B)')
+
+    # Auto-flag remaining mines as a visual cue
+    @rows.times do |r|
+      @cols.times do |c|
+        next unless @mine[r][c] && !@flagged[r][c]
+        @flagged[r][c] = true
+        set_cell_image(r, c, :flag)
+      end
+    end
+    @app.command(:set, @mine_var, 0)
+  end
+
+  def game_over_lose(_hit_r, _hit_c)
+    @game_over = true
+    stop_timer
+    @app.command(@face, :configure, text: ':(')
+
+    @rows.times do |r|
+      @cols.times do |c|
+        set_cell_image(r, c, :mine) if @mine[r][c]
+      end
+    end
+  end
+
+  # -- Timer ---------------------------------------------------------------
+
+  # app.after(ms) schedules a Ruby block to run after a delay. It's a
+  # one-shot timer, so for repeating work we schedule the next tick at the
+  # end of each callback. Checking @timer_running lets us stop the chain
+  # cleanly -- the next queued tick just returns without rescheduling.
+  def start_timer
+    @timer_running = true
+    @app.after(1000) { tick_timer }
+  end
+
+  def stop_timer
+    @timer_running = false
+  end
+
+  def tick_timer
+    return unless @timer_running
+    @elapsed += 1
+    @app.command(:set, @time_var, @elapsed)
+    @app.after(1000) { tick_timer }
+  end
+
+  # -- Helpers -------------------------------------------------------------
+
+  def in_bounds?(r, c)
+    r >= 0 && r < @rows && c >= 0 && c < @cols
+  end
+
+  # Return [row, col] pairs for all valid neighbors of a cell (up to 8).
+  def neighbors(r, c)
+    [[-1, -1], [-1, 0], [-1, 1],
+     [0, -1],           [0, 1],
+     [1, -1],  [1, 0],  [1, 1]].filter_map do |dr, dc|
+      nr, nc = r + dr, c + dc
+      [nr, nc] if in_bounds?(nr, nc)
+    end
+  end
+
+  # Swap a cell's displayed image. "itemconfigure" changes properties of an
+  # existing canvas item by its numeric ID -- here we just swap -image.
+  def set_cell_image(r, c, key)
+    @app.command(@canvas, :itemconfigure, @cell_id[r][c], image: @img[key])
+  end
+end
+
+# -- Main ------------------------------------------------------------------
+
+# track_widgets: false because we manage canvas items ourselves and don't
+# need Teek's automatic widget tracking overhead.
+app = Teek::App.new(track_widgets: false)
+
+# The root window starts withdrawn by default in Teek -- show it.
+app.show
+
+Minesweeper.new(app)
+
+# Automated demo support (for rake docker:test and recording)
+require_relative '../../lib/teek/demo_support'
+TeekDemo.app = app
+
+if TeekDemo.testing?
+  TeekDemo.after_idle do
+    app.after(500) { TeekDemo.finish }
+  end
+end
+
+app.mainloop