mittens_ui 0.0.14 → 0.0.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2479146dca0d7b1cacd610a6c50d8d04df41c8678db14f1b97950ab62b377a63
-  data.tar.gz: 3d86bd7ce738e1a530bd983d26a17a6fe4f2255dc3654d4f203624ceaa634138
+  metadata.gz: ce8a7d0aa1723a2134b6364e0e6fda2c2b9cd4e91b4e05c4f4ca6e948428c643
+  data.tar.gz: 34d9f15cb0cae6dedbc33bd62a8e2a137c06323d196fb607295ddd47b66196a2
 SHA512:
-  metadata.gz: 5e780dfaf16f6657fb955e664470c2ba816290b4d2a05d0f002cb8b810008d6dc7fc92c5cd0115bd10176ca83fafff55f9833de65c8006f37e8f479357137021
-  data.tar.gz: accbcf0f8c5f3114fe5a974a268c4c479bc067eb2aae596450e0e7fa074090c5f81b8a306fbd2028f6a039109781adbe9c784076b2564bb16a04f851024d7cd0
+  metadata.gz: 3528b40c3376faf23d93874d84247cfa6bcfa4b59f932a3e6000090619aa26c7dba5a2ff617f8530ca1cb62096f97ac533a4235da5ba91479e2dc9fa2601bb9d
+  data.tar.gz: b1c75473975e722ca380dda49dba9566128bc8becae1e6937a7e02a543361b367f5eb57a7b9c6837e980c95e7fa837583ce85a20c55c076ff4c3b664789ab932

data/Gemfile

@@ -1,6 +1,6 @@
 source "https://rubygems.org"
 
-ruby "4.0.0"
+ruby "4.0.3"
 
 # Specify your gem's dependencies in mittens_ui.gemspec
 gemspec

data/README.md

@@ -243,27 +243,14 @@ img = MittensUi::Image.new("./assets/animation.gif")
 ### TableView
 ```ruby
 table = MittensUi::TableView.new(
-  headers: ["Name", "Email"],
-  data: [
-    ["John", "john@example.com"],
-    ["Jane", "jane@example.com"]
-  ],
+  ['Name', 'Email'],
+  [['John', 'john@example.com']]
 )
 
-table.add(["Bob", "bob@example.com"])
-table.add(["First", "first@example.com"], :prepend)
+table.add(['Jane', 'jane@example.com'])
 
-table.remove_selected
-
-puts table.row_count
-
-puts table.selected_row.inspect
-
-# Single click on the row
 table.row_clicked { |row| puts row.inspect }
-
-# Double click on the row
-table.row_double_clicked { |row| puts row.inspect }
+table.row_double_clicked { |row| puts "Double: #{row.inspect}" }
 ```
 
 ### Alert

data/examples/contacts.rb

@@ -2,6 +2,7 @@ require '../lib/mittens_ui'
 
 app_options = { name: 'contacts', title: 'Contacts', height: 680, width: 600, can_resize: true }.freeze
 
+
 MittensUi::Application.Window(app_options) do
   puts MittensUi::Application.store.get(:last_selected_contact)
 
@@ -25,63 +26,39 @@ MittensUi::Application.Window(app_options) do
   # --- Contacts Table ---
   MittensUi::Separator.new(:horizontal, top: 2, bottom: 2)
 
-contacts_table = MittensUi::TableView.new(
-  ['Name', 'Email', 'Phone'],
-  [
-    ['John Appleseed', 'john@example.com', '555-1234'],
-    ['Jane Doe', 'jane@example.com', '555-5678'],
-    ['Michael Smith', 'michael.smith@email.com', '555-1001'],
-    ['Emily Johnson', 'emily.j@email.com', '555-1002'],
-    ['Chris Evans', 'cevans@email.com', '555-1003'],
-    ['Olivia Brown', 'olivia.b@email.com', '555-1004'],
-    ['Daniel Wilson', 'dan.w@email.com', '555-1005'],
-    ['Sophia Martinez', 'sophia.m@email.com', '555-1006'],
-    ['James Anderson', 'j.anderson@email.com', '555-1007'],
-    ['Isabella Thomas', 'isabella.t@email.com', '555-1008'],
-    ['Benjamin Taylor', 'ben.taylor@email.com', '555-1009'],
-    ['Mia Moore', 'mia.moore@email.com', '555-1010'],
-    ['Lucas Jackson', 'lucas.j@email.com', '555-1011'],
-    ['Charlotte White', 'charlotte.w@email.com', '555-1012'],
-    ['Henry Harris', 'henry.h@email.com', '555-1013'],
-    ['Amelia Martin', 'amelia.m@email.com', '555-1014'],
-    ['Alexander Thompson', 'alex.t@email.com', '555-1015'],
-    ['Evelyn Garcia', 'evelyn.g@email.com', '555-1016'],
-    ['William Martinez', 'will.m@email.com', '555-1017'],
-    ['Harper Robinson', 'harper.r@email.com', '555-1018'],
-    ['Daniel Clark', 'dan.clark@email.com', '555-1019'],
-    ['Abigail Rodriguez', 'abigail.r@email.com', '555-1020'],
-    ['Matthew Lewis', 'matt.lewis@email.com', '555-1021'],
-    ['Ella Lee', 'ella.lee@email.com', '555-1022'],
-    ['David Walker', 'd.walker@email.com', '555-1023'],
-    ['Scarlett Hall', 'scarlett.h@email.com', '555-1024'],
-    ['Joseph Allen', 'j.allen@email.com', '555-1025'],
-    ['Grace Young', 'grace.y@email.com', '555-1026'],
-    ['Samuel King', 'sam.king@email.com', '555-1027'],
-    ['Chloe Wright', 'chloe.w@email.com', '555-1028'],
-    ['Andrew Scott', 'andrew.s@email.com', '555-1029'],
-    ['Victoria Green', 'victoria.g@email.com', '555-1030'],
-    ['Joshua Adams', 'josh.adams@email.com', '555-1031'],
-    ['Lily Baker', 'lily.b@email.com', '555-1032'],
-    ['Ryan Nelson', 'ryan.n@email.com', '555-1033'],
-    ['Zoey Carter', 'zoey.c@email.com', '555-1034'],
-    ['Nathan Mitchell', 'nathan.m@email.com', '555-1035'],
-    ['Hannah Perez', 'hannah.p@email.com', '555-1036'],
-    ['Aaron Roberts', 'aaron.r@email.com', '555-1037'],
-    ['Sofia Turner', 'sofia.t@email.com', '555-1038'],
-    ['Caleb Phillips', 'caleb.p@email.com', '555-1039'],
-    ['Avery Campbell', 'avery.c@email.com', '555-1040'],
-    ['Ethan Parker', 'ethan.p@email.com', '555-1041'],
-    ['Madison Evans', 'madison.e@email.com', '555-1042'],
-    ['Logan Edwards', 'logan.e@email.com', '555-1043'],
-    ['Layla Collins', 'layla.c@email.com', '555-1044'],
-    ['Noah Stewart', 'noah.s@email.com', '555-1045'],
-    ['Riley Sanchez', 'riley.s@email.com', '555-1046'],
-    ['Jack Morris', 'jack.m@email.com', '555-1047'],
-    ['Aria Rogers', 'aria.r@email.com', '555-1048'],
-    ['Sebastian Reed', 'sebastian.r@email.com', '555-1049'],
-    ['Nora Cook', 'nora.c@email.com', '555-1050']
+  first_names = %w[
+    John Jane Michael Emily Chris Olivia Daniel Sophia James Isabella
+    Benjamin Mia Lucas Charlotte Henry Amelia Alexander Evelyn William Harper
+    Daniel Abigail Matthew Ella David Scarlett Joseph Grace Samuel Chloe
+    Andrew Victoria Joshua Lily Ryan Zoey Nathan Hannah Aaron Sofia
+    Caleb Avery Ethan Madison Logan Layla Noah Riley Jack Aria
+    Sebastian Nora Liam Ava Mason Ella Ethan Harper Logan Grace
+  ]
+
+  last_names = %w[
+    Smith Johnson Brown Taylor Anderson Thomas Jackson White Harris Martin
+    Thompson Garcia Martinez Robinson Clark Rodriguez Lewis Lee Walker Hall
+    Allen Young King Wright Scott Green Adams Baker Nelson Carter Mitchell
+    Perez Roberts Turner Phillips Campbell Parker Evans Edwards Collins Stewart
+    Sanchez Morris Rogers Reed Cook Morgan Bell Murphy Bailey Rivera Cooper
   ]
-)
+
+  contacts_data = 1000.times.map do |i|
+    first = first_names.sample
+    last  = last_names.sample
+
+    name  = "#{first} #{last}"
+    email = "#{first.downcase}.#{last.downcase}#{i}@example.com"
+    phone = "555-#{1000 + i}"
+
+    [name, email, phone]
+  end
+
+  contacts_table = MittensUi::TableView.new(
+    ['Name', 'Email', 'Phone'],
+    contacts_data
+  )
+
   contacts_table.row_double_clicked do |row|
     puts "Double clicked: #{row.inspect}"
   end

data/examples/hn.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+require '../lib/mittens_ui'
+
+class HackerNewsClient
+  BASE_URL = 'https://hacker-news.firebaseio.com/v0'
+
+  def self.get_json(path)
+    uri = URI("#{BASE_URL}/#{path}")
+    res = Net::HTTP.get_response(uri)
+    JSON.parse(res.body)
+  end
+
+  def self.top_story_ids
+    get_json('topstories.json')
+  end
+
+  def self.get_item(id)
+    get_json("item/#{id}.json")
+  end
+
+  def self.top_stories(limit = 20)
+    top_story_ids.first(limit).map do |id|
+      get_item(id)
+    end
+  end
+
+  def self.map_stories_to_rows(stories_data)
+    stories_data.map do |story|
+      url = story['url'] || "https://news.ycombinator.com/item?id=#{story['id']}"
+
+      [
+        story['title'] || 'N/A',
+        story['by'] || 'N/A',
+        story['score'] || 0,
+        url
+      ]
+    end
+  end
+end
+
+MittensUi::Application.Window(
+  name: 'hn_viewer',
+  title: 'HN - Top Hacker News Stories',
+  width: 900,
+  height: 600
+) do
+
+  stories = HackerNewsClient.top_stories(100)
+  rows = HackerNewsClient.map_stories_to_rows(stories)
+
+  top_stories_table = MittensUi::TableView.new(
+    %w[Title Author Score URL].freeze,
+    rows,
+    { page_threshold: 20, page_size: 10 }.freeze
+  )
+
+  top_stories_table.row_double_clicked do |row|
+    link = MittensUi::WebLink.new('', row[3])
+    link.open_url
+    link.remove
+  end
+
+  MittensUi::Button.new(title: 'Refresh Stories').click do |btn|
+    btn.loading do
+      stories = HackerNewsClient.top_stories(5)
+      top_stories_table.update_data(HackerNewsClient.map_stories_to_rows(stories))
+    end
+  end
+end

data/examples/keyboard_shortcut_demo.rb

@@ -0,0 +1,71 @@
+require '../lib/mittens_ui'
+
+app_options = {
+  name: 'shortcut_demo',
+  title: 'Keyboard Shortcut Demo',
+  height: 400,
+  width: 500,
+  can_resize: false,
+  theme: :light
+}.freeze
+
+MittensUi::Application.Window(app_options) do
+
+  press_counter = 0
+  status = MittensUi::Label.new('Press a shortcut key...', expand: true, margin: 12)
+
+  MittensUi::Separator.new(:horizontal, top: 8, bottom: 8)
+
+  d_btn = MittensUi::Button.new(title: 'Focus me → ctrl+d (instant)')
+  d_btn.keyboard_shortcut("ctrl", "d") do
+    press_counter += 1
+    status.text = "ctrl+d fired! x#{press_counter.to_s}"
+  end
+
+  MittensUi::Separator.new(:horizontal, top: 8, bottom: 8)
+
+
+  s_btn = MittensUi::Button.new(title: 'Focus me → ctrl+s (2s delay)')
+  s_btn.keyboard_shortcut("ctrl", "s", timer: 2) do
+    press_counter += 1
+    status.text = "ctrl+s fired after 2s! x#{press_counter}"
+  end
+
+  MittensUi::Separator.new(:horizontal, top: 8, bottom: 8)
+
+  tb = MittensUi::Textbox.new(multiline: false, width: :full, placeholder: "write text, press alt+r to clear it!")
+  tb.keyboard_shortcut("alt", "r") do
+    tb.text = ""
+    press_counter += 1
+    status.text = "alt+r fired — text field cleared! x#{press_counter}"
+  end
+
+  # can register multiple keyboard_shortcuts for the same Widget.
+  tb.keyboard_shortcut("alt", "u") do
+    tb.text = tb.text.upcase
+    press_counter += 1
+    status.text = "alt+u fired - text uppercased!  x#{press_counter}"
+  end
+
+  tb.keyboard_shortcut("alt", "d") do
+    tb.text = tb.text.downcase
+    press_counter += 1
+    status.text = "alt+d fired - text downcased!  x#{press_counter}"
+  end
+
+  MittensUi::Separator.new(:horizontal, top: 8, bottom: 8)
+
+  all = []
+  inspection_button = MittensUi::Button.new(title: 'Inspect Shortcuts')
+
+  inspection_button.click do
+    all = [d_btn.shortcuts, s_btn.shortcuts, tb.shortcuts].flatten
+    status.text = "Registered: #{all.join(', ')}"
+  end
+
+  inspection_button.keyboard_shortcut("ctrl", "s") do
+    status.text = "Registered: #{ all.map{ |cmd| cmd.upcase }.join(', ') }"
+  end
+
+  MittensUi::Separator.new(:horizontal, top: 8, bottom: 8)
+end

data/examples/mig.rb

@@ -109,4 +109,17 @@ MittensUi::Application.Window(app_options) do
   MittensUi::Separator.new(:horizontal, top: 10, bottom: 100)
   MittensUi::RadioButton.new({ options: %w[Red Green Blue], layout: :horizontal, bottom: 50 })
 
+  MittensUi::Separator.new(:horizontal, top: 10, bottom: 10)
+
+  status = MittensUi::Label.new('Press a shortcut key...', expand: true, margin: 12)
+
+  MittensUi::Separator.new(:horizontal, top: 8, bottom: 8)
+
+  # Ctrl+D fires instantly on the button
+  d_btn = MittensUi::Button.new(title: 'Focus me → Ctrl+D (instant)')
+  d_btn.keyboard_shortcut("ctrl", "d") do
+    status.text = "Ctrl+D fired!"
+  end
+
+
 end

data/lib/mittens_ui/button.rb

@@ -38,8 +38,8 @@ module MittensUi
     # @option options [Symbol] :width (:full) column width in the layout grid
     # @option options [Boolean] :defer_render (false) skip auto-rendering into layout
     def initialize(options = {})
-      button_title = options[:title] || 'Button'
-      icon_type    = options[:icon]  || nil
+      button_title = options.fetch(:title, 'Button')
+      icon_type    = options.fetch(:icon, nil)
 
       @loading  = false
       @button   = Gtk::Button.new
@@ -53,7 +53,9 @@ module MittensUi
 
       @label = Gtk::Label.new(button_title)
       @box.append(@label)
+      @box.set_halign(:center)
       @box.append(@spinner)
+
       @button.set_child(@box)
       @spinner.hide
 

data/lib/mittens_ui/checkbox.rb

@@ -24,7 +24,7 @@ module MittensUi
     # @option options [Symbol] :width (:full) column width in the layout grid
     # @option options [Boolean] :defer_render (false) skip auto-rendering into layout
     def initialize(options = {})
-      label    = options[:label] || 'Checkbox'
+      label    = options.fetch(:label, 'Checkbox')
       @value   = nil
       @checkbox = Gtk::CheckButton.new
       @checkbox.set_label(label.to_s)

data/lib/mittens_ui/colorpicker.rb

@@ -38,9 +38,9 @@ module MittensUi
     # @yield [picker] called only if the user selected a color
     # @yieldparam picker [MittensUi::ColorPicker] the picker with color data
     def initialize(options = {}, &block)
-      @title    = options[:title]   || 'Pick a Color'
-      @default  = options[:default] || nil
-      @alpha    = options[:alpha]   || false
+      @title    = options.fetch(:title, 'Pick a Color')
+      @default  = options.fetch(:default, nil)
+      @alpha    = options.fetch(:alpha, false)
       @selected = false
       @color    = nil
 

data/lib/mittens_ui/core.rb

@@ -49,11 +49,13 @@ module MittensUi
     # @option options [Integer] :bottom bottom margin in pixels
     # @option options [Integer] :right right margin in pixels
     def initialize(widget, options = {})
-      @core_widget  = widget
+      @core_widget  = widget # This represents the GTK widget.
+      @core_widget.focusable = true
       @width        = options[:width]        || :full
       @defer_render = options[:defer_render] || false
       set_margin_from_opts_for(@core_widget, options)
       render unless @defer_render
+      enable_hover_focus
     end
 
     # Shows the widget if it is hidden.
@@ -108,7 +110,7 @@ module MittensUi
     # Adds the widget to the application layout grid.
     # Called automatically during initialization unless +:defer_render+ is true.
     # Can be overridden in subclasses that require special placement
-    # (e.g. {HeaderBar}, {Notify}).
+    # ({HeaderBar}, {Notify}).
     #
     # @return [void]
     def render
@@ -119,5 +121,111 @@ module MittensUi
         MittensUi::Application.layout.add(@core_widget, width: @width)
       end
     end
+
+
+    # Registers a simple keyboard shortcut on +@core_wiget+ using a modifier + key combination.
+    #
+    # Attaches a +Gtk::EventControllerKey+ to the widget that listens for the given
+    # key combination. The widget must have focus for the shortcut to fire. If a
+    # +timer+ is provided, the block is executed after the specified delay via
+    # +GLib::Timeout+.
+    #
+    # @param modifier [String] The modifier key. Accepts "ctrl", "shift", "alt", or "super".
+    # @param key [String] The key name as a GTK key string ("d", "s", "Return", "Escape").
+    # @param timer [Integer] Seconds to wait before invoking the block. Defaults to 0 (immediate).
+    # @param block [Proc] The block to execute when the shortcut is triggered.
+    #
+    # @example Instant shortcut
+    #   btn.keyboard_shortcut("ctrl", "d") { puts "Ctrl+D fired" }
+    #
+    # @example Delayed shortcut
+    #   btn.keyboard_shortcut("ctrl", "s", timer: 2) { puts "fired after 2s" }
+    #
+    # @return [void]
+    def keyboard_shortcut(modifier, key, timer: 0, &block)
+      @shortcut_controllers ||= []
+
+      controller = Gtk::EventControllerKey.new
+
+      controller.signal_connect("key-pressed") do |_ctrl, keyval, _keycode, state|
+        mod_match = case modifier.to_s.downcase
+                    when "ctrl"  then (state & Gdk::ModifierType::CONTROL_MASK).nonzero?
+                    when "shift" then (state & Gdk::ModifierType::SHIFT_MASK).nonzero?
+                    when "alt"   then (state & Gdk::ModifierType::ALT_MASK).nonzero?
+                    when "super" then (state & Gdk::ModifierType::SUPER_MASK).nonzero?
+                    else false
+                    end
+
+        key_match = (keyval == Gdk::Keyval.from_name(key))
+
+        if mod_match && key_match
+          if timer > 0
+            GLib::Timeout.add(timer * 1000) do
+              block.call
+              GLib::Source::REMOVE
+            end
+          else
+            block.call
+          end
+          true  # consume the event
+        else
+          false
+        end
+      end
+
+      @shortcut_controllers << { modifier: modifier, key: key, controller: controller }
+      @core_widget.add_controller(controller)
+    end
+
+    # Removes a previously registered keyboard shortcut from +@core_widget+.
+    #
+    # Finds the shortcut matching the given +modifier+ and +key+ combination,
+    # detaches its +Gtk::EventControllerKey+ from the underlying GTK widget.
+    #
+    # If no matching shortcut is found, this is a no-op.
+    #
+    # @param modifier [String] The modifier key used when registering the shortcut ("ctrl").
+    # @param key [String] The key name used when registering the shortcut ("d").
+    #
+    # @example
+    #   btn.remove_shortcut("ctrl", "d")
+    #
+    # @return [void]
+    def remove_keyboard_shortcut(modifier, key)
+      @shortcut_controllers&.reject! do |entry|
+        if entry[:modifier] == modifier && entry[:key] == key
+          @gtk_widget.remove_controller(entry[:controller])
+          true
+        end
+      end
+    end
+
+    # Returns a list of all keyboard shortcuts registered on +@core_wiget+.
+    #
+    # Each shortcut is represented as a human-readable string in the format
+    # "modifier+key" ("ctrl+d", "alt+r").
+    #
+    # @example
+    #   btn.shortcuts # => ["ctrl+d", "ctrl+s"]
+    #
+    # @return [Array<String>] Registered shortcuts, or an empty array if none.
+    def shortcuts
+      @shortcut_controllers&.map { |e| "#{e[:modifier]}+#{e[:key]}" } || []
+    end
+
+    private
+
+    # Grants focus to the +@core_wiget+ when the mouse pointer enters it.
+    #
+    # Attaches a +Gtk::EventControllerMotion+ and sets +focusable+ to +true+,
+    # which is required for +grab_focus+ to work with GTK4 wigets.
+    #
+    # @return [void]
+    def enable_hover_focus
+      @core_widget.focusable = true
+      motion = Gtk::EventControllerMotion.new
+      motion.signal_connect("enter") { @core_widget.grab_focus }
+      @core_widget.add_controller(motion)
+    end
   end
 end

data/lib/mittens_ui/header_bar.rb

@@ -25,8 +25,8 @@ module MittensUi
     #   Accepted values are +:left+ and +:right+
     # @option options [Boolean] :defer_render (false) skip auto-rendering into layout
     def initialize(widgets, options = {})
-      title    = options[:title]    || ''
-      position = options[:position] || :left
+      title    = options.fetch(:title, '')
+      position = options.fetch(:position, :left)
 
       @header = Gtk::HeaderBar.new
 
@@ -36,9 +36,8 @@ module MittensUi
       title_label = Gtk::Label.new(title)
       @header.title_widget = title_label
 
-
       box = Gtk::Box.new(:horizontal, 0)
-      box.add_css_class("linked")
+      box.add_css_class('linked')
 
       widgets.each do |w|
         w.remove

data/lib/mittens_ui/knob.rb

@@ -210,7 +210,7 @@ module MittensUi
 
       # value text
       cr.set_source_rgb(0.9, 0.9, 0.9)
-      cr.set_font_size(9)
+      cr.set_font_size(10.4)
       text = value.to_s
       extents = cr.text_extents(text)
       cr.move_to(cx - extents.width / 2, cy + extents.height / 2)

data/lib/mittens_ui/label.rb

@@ -32,5 +32,15 @@ module MittensUi
       gtk_label = Gtk::Label.new(text)
       super(gtk_label, options)
     end
+
+    # @return [String] returns the current label text.
+    def text
+      @core_widget.label
+    end
+
+    # @param value [String] A String value that the label gets set to
+    def text=(value)
+      @core_widget.set_label(value.to_s)
+    end
   end
 end

data/lib/mittens_ui/table_view.rb

@@ -3,13 +3,14 @@
 require 'mittens_ui/core'
 
 module MittensUi
-  # A simple, but custom table widget built on {Gtk::Grid}.
+  # A simple, custom table widget built on Gtk::Grid.
   #
-  # Provides:
-  # - Column headers with sorting (▲ ▼ indicators)
-  # - Row selection
-  # - Single-click and double-click callbacks
-  # - Dynamic row insertion
+  # Features:
+  # - Sorting with ▲ ▼ indicators
+  # - Row selection (mouse + keyboard)
+  # - Single & double click callbacks
+  # - Pagination for large datasets (auto-enabled > 500 rows)
+  # - Built-in pagination UI (Prev / Next buttons + page indicator)
   # - Dark mode friendly styling
   #
   # @example Basic usage
@@ -21,23 +22,31 @@ module MittensUi
   # @example Add row
   #   table.add(['Jane', 'jane@example.com'])
   #
-  # @example Click handlers
-  #   table.row_clicked { |row| puts row.inspect }
-  #   table.row_double_clicked { |row| puts "Double: #{row.inspect}" }
+  # @example Pagination (automatic)
+  #   # Pagination UI appears automatically when data > 500 rows, unless you change it by using options hash.
   #
   class TableView < Core
     attr_reader :data, :headers, :selected_row_idx
 
-    # @param headers [Array<String>] column headers
-    # @param data [Array<Array<String>>] initial rows
-    # @param options [Hash] Core layout options
+    PAGE_THRESHOLD = 500
+    PAGE_SIZE      = 100
+
     def initialize(headers = [], data = [], options = {})
       @headers = headers
       @data = data
+
       @row_widgets = []
       @header_labels = []
       @selected_row_idx = nil
       @sort_directions = {}
+      @current_page = 0
+
+      @page_threshold = options.fetch(:page_threshold, PAGE_THRESHOLD)
+      @page_size = options.fetch(:page_size, PAGE_SIZE)
+
+      # ---------------------------
+      # GTK Structure
+      # ---------------------------
 
       @grid = Gtk::Grid.new
       @grid.set_column_spacing(0)
@@ -46,102 +55,147 @@ module MittensUi
       @scroller = Gtk::ScrolledWindow.new
       @scroller.set_policy(:automatic, :automatic)
       @scroller.set_child(@grid)
+      @scroller.set_vexpand(true)
+      @scroller.set_min_content_height(300)
+      @scroller.set_max_content_height(300)
+
+      # Pagination UI
+      @pagination_box = Gtk::Box.new(:horizontal, 10)
+      @pagination_box.set_margin_top(10)
+      @pagination_box.set_halign(:center)
 
-      # Calculate height of table:
-      row_height = 24
-      header_height = 40
-      max_height = 300
-      desired_height = [(@data.size * row_height) + header_height, max_height].min
+      @prev_btn = Gtk::Button.new(label: '← Prev')
+      @next_btn = Gtk::Button.new(label: 'Next →')
+      @page_label = Gtk::Label.new('')
 
-      # Set the scroller's min and max height
-      @scroller.set_min_content_height(desired_height)
-      @scroller.set_max_content_height(desired_height)
+      @prev_btn.signal_connect('clicked') { prev_page }
+      @next_btn.signal_connect('clicked') { next_page }
 
-      super(@scroller, options)
+      @pagination_box.append(@prev_btn)
+      @pagination_box.append(@page_label)
+      @pagination_box.append(@next_btn)
 
-      # Click handling
+      # Root container (important for Core)
+      @container = Gtk::Box.new(:vertical, 0)
+      @container.append(@scroller)
+      @container.append(@pagination_box)
+
+      super(@container, options)
+
+      # Events
       @on_row_clicked = nil
       @on_row_double_clicked = nil
       @last_click_time = nil
       @last_clicked_row = nil
 
       setup_css
+      setup_keyboard
+
       render_headers
       render_rows
+      update_pagination_ui
     end
 
     # ---------------------------
     # Public API
     # ---------------------------
 
-    # Add a row to the table
-    #
-    # @param row [Array<String>] row data
-    # @param direction [Symbol] :append or :prepend
-    # @return [void]
     def add(row, direction = :append)
       return if row.nil? || row.empty?
 
-      if direction == :prepend
-        @data.unshift(row)
-      else
-        @data << row
-      end
+      direction == :prepend ? @data.unshift(row) : @data << row
 
+      adjust_page_after_insert
       render_rows
+      update_pagination_ui
     end
 
-    # Replace table data
-    #
-    # @param new_data [Array<Array<String>>]
     def update_data(new_data)
       @data = new_data
+      @current_page = 0
       render_rows
+      update_pagination_ui
     end
 
-    # Check if a row is selected
-    #
-    # @param idx [Integer, nil]
-    # @return [Boolean]
     def row_selected?(idx = nil)
       return !@selected_row_idx.nil? if idx.nil?
+
       @selected_row_idx == idx
     end
 
-    # Get selected row data
-    #
-    # @return [Array<String>, nil]
     def selected_row
       return nil unless @selected_row_idx
+
       @data[@selected_row_idx]
     end
 
-    # Remove selected row
-    #
-    # @return [Array<String>, nil]
     def remove_selected
       return nil unless @selected_row_idx
 
       removed = @data.delete_at(@selected_row_idx)
       @selected_row_idx = nil
       render_rows
+      update_pagination_ui
       removed
     end
 
-    # Register single-click handler
-    #
-    # @yield [row] row data
     def row_clicked(&block)
       @on_row_clicked = block
     end
 
-    # Register double-click handler
-    #
-    # @yield [row] row data
     def row_double_clicked(&block)
       @on_row_double_clicked = block
     end
 
+    # ---------------------------
+    # Pagination
+    # ---------------------------
+
+    def paginated_data
+      return @data if @data.size <= @page_threshold
+
+      start = @current_page * @page_size
+      @data.slice(start, @page_size) || []
+    end
+
+    def next_page
+      return if @data.size <= @page_threshold
+
+      max_page = (@data.size / @page_size.to_f).ceil - 1
+      @current_page = [@current_page + 1, max_page].min
+      render_rows
+      update_pagination_ui
+    end
+
+    def prev_page
+      return if @data.size <= @page_threshold
+
+      @current_page = [@current_page - 1, 0].max
+      render_rows
+      update_pagination_ui
+    end
+
+    def adjust_page_after_insert
+      return if @data.size <= @page_threshold
+
+      @current_page = (@data.size / @page_size.to_f).floor
+    end
+
+    def update_pagination_ui
+      if @data.size <= @page_threshold
+        @pagination_box.hide
+        return
+      end
+
+      total_pages = (@data.size / @page_size.to_f).ceil
+      @page_label.set_label("#{@current_page + 1} / #{total_pages}")
+
+      @prev_btn.set_sensitive(@current_page > 0)
+      @next_btn.set_sensitive(@current_page < total_pages - 1)
+
+      @pagination_box.show
+    end
+
     # ---------------------------
     # Rendering
     # ---------------------------
@@ -151,37 +205,35 @@ module MittensUi
     def setup_css
       css = Gtk::CssProvider.new
       css.load(data: <<~CSS)
-        frame {
-          border-radius: 0;
-          box-shadow: none;
-          border: none;
-        }
-
-        .table-cell {
+        box.table-cell {
           padding: 6px 10px;
           border-bottom: 1px solid @borders;
+          background-color: @theme_base_color;
+          color: @theme_text_color;
         }
 
-        .header-cell {
+        box.header-cell {
           font-weight: bold;
           padding: 8px 10px;
           border-bottom: 2px solid @borders;
-          background-color: @theme_base_color;
+          background-color: shade(@theme_base_color, 0.95);
+          color: @theme_text_color;
         }
 
-        .row-even {
-          background-color: alpha(@theme_bg_color, 0.96);
+        box.row-even {
+          background-color: shade(@theme_base_color, 1.00);
         }
 
-        .row-odd {
-          background-color: alpha(@theme_bg_color, 0.90);
+        box.row-odd {
+          background-color: shade(@theme_base_color, 0.97);
         }
 
-        .table-cell:hover {
-          background-color: alpha(@theme_selected_bg_color, 0.25);
+        box.table-cell:hover {
+          background-color: @theme_selected_bg_color;
+          color: @theme_selected_fg_color;
         }
 
-        .row-selected {
+        box.row-selected {
           background-color: @theme_selected_bg_color;
           color: @theme_selected_fg_color;
         }
@@ -190,7 +242,7 @@ module MittensUi
       Gtk::StyleContext.add_provider_for_display(
         Gdk::Display.default,
         css,
-        Gtk::StyleProvider::PRIORITY_USER
+        Gtk::StyleProvider::PRIORITY_APPLICATION
       )
     end
 
@@ -202,19 +254,15 @@ module MittensUi
 
         @header_labels[col_idx] = label
 
-        frame = Gtk::Frame.new
-        frame.set_child(label)
-        frame.set_hexpand(true)
-        frame.style_context.add_class('header-cell')
+        box = Gtk::Box.new(:horizontal, 0)
+        box.append(label)
+        box.style_context.add_class('header-cell')
 
         gesture = Gtk::GestureClick.new
-        gesture.set_button(0)
-        gesture.signal_connect("pressed") do |_g, _n, _x, _y|
-          sort_column(col_idx)
-        end
-        frame.add_controller(gesture)
+        gesture.signal_connect('pressed') { sort_column(col_idx) }
+        box.add_controller(gesture)
 
-        @grid.attach(frame, col_idx, 0, 1, 1)
+        @grid.attach(box, col_idx, 0, 1, 1)
       end
     end
 
@@ -222,8 +270,11 @@ module MittensUi
       @row_widgets.each { |row| row.each { |w| @grid.remove(w) } }
       @row_widgets.clear
 
-      @data.each_with_index do |row, row_idx|
-        base_class = row_idx.even? ? 'row-even' : 'row-odd'
+      rows = paginated_data
+
+      rows.each_with_index do |row, visible_idx|
+        actual_idx = visible_idx + (@current_page * PAGE_SIZE)
+        base_class = visible_idx.even? ? 'row-even' : 'row-odd'
         widget_row = []
 
         row.each_with_index do |cell, col_idx|
@@ -231,46 +282,17 @@ module MittensUi
           label.set_xalign(0.0)
           label.set_hexpand(true)
 
-          frame = Gtk::Frame.new
-          frame.set_child(label)
-          frame.set_hexpand(true)
-          frame.style_context.add_class('table-cell')
-          frame.style_context.add_class(base_class)
-          frame.style_context.add_class('row-selected') if row_selected?(row_idx)
-
-          gesture = Gtk::GestureClick.new
-          gesture.set_button(0)
-
-          gesture.signal_connect("pressed") do |_g, _n, _x, _y|
-            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-            if @last_click_time &&
-               @last_clicked_row == row_idx &&
-               (now - @last_click_time) < 0.3
-
-              # DOUBLE CLICK
-              @on_row_double_clicked&.call(@data[row_idx])
-            else
-              # SINGLE CLICK (delayed slightly to avoid conflict)
-              GLib::Timeout.add(250) do
-                if @last_clicked_row == row_idx
-                  @on_row_clicked&.call(@data[row_idx])
-                end
-                false
-              end
-            end
-
-            @last_click_time = now
-            @last_clicked_row = row_idx
-            @selected_row_idx = row_idx
-
-            render_rows
-          end
+          box = Gtk::Box.new(:horizontal, 0)
+          box.append(label)
 
-          frame.add_controller(gesture)
+          box.style_context.add_class('table-cell')
+          box.style_context.add_class(base_class)
+          box.style_context.add_class('row-selected') if row_selected?(actual_idx)
 
-          @grid.attach(frame, col_idx, row_idx + 1, 1, 1)
-          widget_row << frame
+          attach_click_handlers(box, actual_idx)
+
+          @grid.attach(box, col_idx, visible_idx + 1, 1, 1)
+          widget_row << box
         end
 
         @row_widgets << widget_row
@@ -280,21 +302,91 @@ module MittensUi
       @row_widgets.flatten.each(&:show)
     end
 
+    def attach_click_handlers(widget, row_idx)
+      gesture = Gtk::GestureClick.new
+      gesture.set_button(0)
+
+      gesture.signal_connect('pressed') do |_g, _n, _x, _y|
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        if @last_click_time &&
+           @last_clicked_row == row_idx &&
+           (now - @last_click_time) < 0.3
+
+          @on_row_double_clicked&.call(@data[row_idx])
+        else
+          GLib::Timeout.add(200) do
+            @last_clicked_row == row_idx ? @on_row_clicked&.call(@data[row_idx]) : false
+          end
+        end
+
+        @last_click_time = now
+        @last_clicked_row = row_idx
+        @selected_row_idx = row_idx
+
+        render_rows
+      end
+
+      widget.add_controller(gesture)
+    end
+
     def sort_column(col_idx)
       dir = @sort_directions[col_idx] ? :desc : :asc
       @sort_directions[col_idx] = !@sort_directions[col_idx]
 
       @header_labels.each_with_index do |lbl, i|
-        lbl.set_label(@headers[i].to_s) if lbl
+        lbl.set_label(@headers[i])
       end
 
-      arrow = dir == :asc ? "  ▲" : "  ▼"
+      arrow = dir == :asc ? ' ▲' : ' ▼'
       @header_labels[col_idx].set_label(@headers[col_idx] + arrow)
 
-      @data.sort_by! { |row| row[col_idx].to_s }
+      @data.sort_by! do |row|
+        val = row[col_idx]
+
+        case val
+        when Integer
+          val
+        when Float
+          val
+        when String
+          # try numeric string first
+          Integer(val) rescue Float(val) rescue val.downcase
+        else
+          val.to_s
+        end
+      end
+
       @data.reverse! if dir == :desc
 
+      render_rows
+      update_pagination_ui
+    end
+
+    def setup_keyboard
+      controller = Gtk::EventControllerKey.new
+
+      controller.signal_connect('key-pressed') do |_ctrl, key, _, _|
+        case key
+        when Gdk::Keyval::KEY_Up
+          move_selection(-1)
+        when Gdk::Keyval::KEY_Down
+          move_selection(1)
+        when Gdk::Keyval::KEY_Return
+          @on_row_double_clicked&.call(selected_row)
+        end
+      end
+
+      @scroller.add_controller(controller)
+    end
+
+    def move_selection(delta)
+      return if @data.empty?
+
+      @selected_row_idx ||= 0
+      @selected_row_idx = [[@selected_row_idx + delta, 0].max, @data.size - 1].min
+
       render_rows
     end
   end
-end
+end

data/lib/mittens_ui/textbox.rb

@@ -69,6 +69,15 @@ module MittensUi
       end
     end
 
+    # @param value [String] A String value that the label gets set to
+    def text=(value)
+      if @multiline
+        @text_buffer.text = value.to_s
+      else
+        @textbox.text = value.to_s
+      end
+    end
+
     # Clears all text from the widget.
     # Works in both single-line and multiline mode.
     #

data/lib/mittens_ui/version.rb

@@ -1,3 +1,3 @@
 module MittensUi
-  VERSION = "0.0.14"
+  VERSION = "0.0.16"
 end

data/lib/mittens_ui/web_link.rb

@@ -43,5 +43,13 @@ module MittensUi
       @web_link = Gtk::LinkButton.new(@url, @name)
       super(@web_link, options)
     end
+
+    # Opens the set @url link in a web browser.
+    #
+    # @return [void]
+    def open_url
+      launcher = Gtk::UriLauncher.new(@url)
+      launcher.launch
+    end
   end
 end

data/mittens_ui.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
   #spec.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'"
 
   spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/tuttza/mittens_ui"
+  spec.metadata["source_code_uri"] = "https://codeberg.org/tuttza/mittens_ui"
   #spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
 
   # Specify which files should be added to the gem when it is released.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mittens_ui
 version: !ruby/object:Gem::Version
-  version: 0.0.14
+  version: 0.0.16
 platform: ruby
 authors:
 - Zach Tuttle
@@ -112,6 +112,8 @@ files:
 - examples/assets/gnome_logo.png
 - examples/assets/mittens_ui_preview.gif
 - examples/contacts.rb
+- examples/hn.rb
+- examples/keyboard_shortcut_demo.rb
 - examples/mig.rb
 - lib/mittens_ui.rb
 - lib/mittens_ui/alert.rb
@@ -150,7 +152,7 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/tuttza/mittens_ui
-  source_code_uri: https://github.com/tuttza/mittens_ui
+  source_code_uri: https://codeberg.org/tuttza/mittens_ui
 rdoc_options: []
 require_paths:
 - lib
@@ -165,7 +167,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: A tiny GUI toolkit written on top of GTK
 test_files: []