qt 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6d1a405c62cfb867d7799098163f4dff1122b3c92aa065ee0397ca499c0c4137
+  data.tar.gz: 7d731f1d727f82a96d1e1f8b910aa953f0d727bcc0ee2026e8da5ba3e536ad67
+SHA512:
+  metadata.gz: 0bcc6466742ddd75c5e81d38ccaf77b8767092f16de9abc4206735d5b7a34d8af2223c0a90efe67333f91aa7adca6f210901b121c32e6b8c7d1108a618065dc7
+  data.tar.gz: 1d55595b8845d119bbc11f60518281b1fea8ef5f3aa55698b174bf4e63d31e39d8771515c9980fc5cfe1d593a362193acd2159432a5be4b9e77218b870c78385

data/LICENSE

@@ -0,0 +1,27 @@
+SPDX-License-Identifier: BSD-2-Clause
+
+BSD 2-Clause License
+
+Copyright (c) 2026, Maksim Veynberg
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,303 @@
+# qt
+
+![Ruby](https://img.shields.io/badge/Ruby-3.1%2B-CC342D)
+![Qt](https://img.shields.io/badge/Qt-6.10%2B-41CD52)
+![Status](https://img.shields.io/badge/Status-Experimental-orange)
+![Bridge](https://img.shields.io/badge/Architecture-Ruby%20%E2%86%94%20Qt%20Bridge-blue)
+
+Ruby-first Qt 6.10+ bridge.
+
+Build real Qt Widgets apps in pure Ruby, mutate them live from IRB, and keep C/C++ surface minimal via generated bridge code from system Qt headers.
+
+## Why It Hits Different
+
+- Pure Ruby usage: no QML, no extra UI language.
+- Real Qt power: `QApplication`, `QWidget`, `QLabel`, `QPushButton`, `QVBoxLayout`.
+- Ruby ergonomics: Qt-style and snake_case/property style in parallel.
+- Live GUI hacking: update widgets while the window is open.
+- Generated bridge: API is derived from system Qt headers.
+
+## 30-Second Wow
+
+```bash
+ruby examples/development_ordered_demos/02_live_layout_console.rb
+```
+
+Then in IRB:
+
+```ruby
+add_label("Release pipeline")
+add_button("Run")
+remove_last
+
+gui { window.resize(1100, 700) }
+items.last&.q_inspect
+```
+
+## Before -> After
+
+Before (typical static run):
+
+```ruby
+app = QApplication.new(0, [])
+window = QWidget.new
+window.show
+app.exec
+```
+
+After (live dev loop):
+
+```ruby
+# app already running
+add_label("Dynamic block")
+add_button("Ship")
+gui { window.set_window_title("Changed live") }
+```
+
+## Install
+
+### Requirements
+
+- Ruby 3.1+
+- Qt 6.10+ dev packages (`Qt6Core`, `Qt6Gui`, `Qt6Widgets` via `pkg-config`)
+- C++17 compiler
+
+Check Qt:
+
+```bash
+pkg-config --modversion Qt6Widgets
+```
+
+### Build from repo
+
+```bash
+bundle install
+bundle exec rake compile
+bundle exec rake install
+```
+
+`rake install` installs into your current Ruby environment (including active `rbenv` version).
+`rake compile` builds the full bridge with `QT_RUBY_SCOPE=all` by default.
+
+### Gem usage
+
+```bash
+gem install qt
+```
+
+## Hello Qt in Ruby
+
+```ruby
+require 'qt'
+
+app = QApplication.new(0, [])
+
+window = QWidget.new do |w|
+  w.set_window_title('Qt Ruby App')
+  w.resize(800, 600)
+end
+
+label = QLabel.new(window)
+label.text = 'Hello from Ruby + Qt'
+label.set_alignment(Qt::AlignCenter)
+label.set_geometry(0, 0, 800, 600)
+
+app.exec
+```
+
+## API Style: Qt + Ruby
+
+```ruby
+# Qt style
+label.setText('A')
+window.setWindowTitle('Main')
+
+# Ruby style
+label.text = 'B'
+window.window_title = 'Main 2'
+puts label.text
+```
+
+## API Compatibility Notes
+
+Generated Ruby API is intentionally close to Qt API, but follows universal bridge policies.
+
+- `snake_case` aliases are generated for Qt camelCase methods.
+- Ruby keyword-safe renaming is applied when needed: `next` -> `next_`.
+- Default C++ arguments are surfaced as optional Ruby arguments.
+- Internal runtime name collisions are renamed consistently:
+  - Qt `handle(int)` is exposed as `handle_at(int)` because `handle` is used for native object pointer access.
+- Property convenience API is generated from Qt setters/getters when available:
+  - `setText(...)` -> `text=(...)`, `text`.
+- Runtime event/signal convenience methods are Ruby-layer helpers (not raw Qt method names):
+  - `on(event, &block)` / alias `on_event`
+  - `off(event = nil)` / alias `off_event`
+  - `connect(signal, &block)` / aliases `on_signal`, `slot`
+  - `disconnect(signal = nil)` / alias `off_signal`
+  - these helpers are mixed into generated `QObject` descendants (for example `QWidget`, `QPushButton`, `QTimer`)
+  - non-`QObject` value classes (`QIcon`, `QPixmap`, `QImage`) intentionally do not expose `connect`/`on`
+  - event delivery is target-first with nearest watched ancestor fallback for interactive events (mouse/key/focus/enter/leave)
+- Introspection helpers are Ruby-layer helpers:
+  - `q_inspect`, aliases `qt_inspect`, `to_h`
+- Top-level constant aliases are provided for convenience:
+  - `QApplication`, `QWidget`, `QLabel`, `QPushButton`, `QLineEdit`, `QVBoxLayout`, `QTableWidget`, `QTableWidgetItem`, `QScrollArea`
+- Methods with unsupported signatures are skipped by policy:
+  - non-public, deprecated, operator/internal event hooks,
+  - non-FFI-safe argument/return types.
+
+## Introspection
+
+Every generated object exposes API snapshot helpers:
+
+```ruby
+label.q_inspect
+label.qt_inspect
+label.to_h
+```
+
+Shape:
+
+```ruby
+{
+  qt_class: "QLabel",
+  ruby_class: "Qt::QLabel",
+  qt_methods: ["setText", "setAlignment", "text", ...],
+  ruby_methods: [:setText, :set_text, :text, ...],
+  properties: { text: "A", alignment: 129 }
+}
+```
+
+## Examples
+
+```bash
+ruby examples/development_ordered_demos/01_dsl_hello.rb
+ruby examples/development_ordered_demos/02_live_layout_console.rb
+```
+
+QObject signal example:
+
+```ruby
+timer = QTimer.new
+timer.set_interval(1000)
+timer.connect('timeout') { puts 'tick' }
+timer.start
+```
+
+## Architecture
+
+1. `scripts/generate_bridge.rb` reads Qt API from system headers.
+2. Generates:
+- `build/generated/qt_ruby_bridge.cpp`
+- `build/generated/bridge_api.rb`
+- `build/generated/widgets.rb`
+3. Compiles native extension into `build/qt/qt_ruby_bridge.so`.
+4. Ruby layer calls bridge functions via `ffi`.
+
+Everything generated/build-related is under `build/` and should stay out of git.
+
+## Layout
+
+- `lib/qt` public Ruby API
+- `scripts/generate_bridge.rb` AST-driven bridge generator
+- `ext/qt_ruby_bridge` native extension entrypoint
+- `build/generated` generated sources
+- `build/qt` compiled bridge `.so`
+- `examples` demos
+- `test` tests
+
+## Roadmap
+
+### Done
+
+- AST-driven generation with scope support: `QT_RUBY_SCOPE=widgets|qobject|all`
+- default compile path switched to `all` (`widgets + qobject`)
+- generated Qt inheritance in Ruby classes (including intermediate Qt wrappers)
+- Qt-native event/signal runtime wired to Ruby at QObject level (`on`, `connect`, `disconnect`)
+- `QTimer` available in generated API with `connect('timeout')` support
+- `06_timetrap_clockify` moved to `app.exec` + `QTimer` update loop (no manual polling loop)
+- QObject styling hooks exposed for QSS selectors:
+  - `setObjectName` / `object_name=`
+  - `setProperty` / `property` (via QVariant bridge codec)
+- window icon support from generated API:
+  - `QIcon.new(path)`
+  - `QWidget#setWindowIcon` / `set_window_icon`
+
+### Next
+
+- typed signal payloads (not only raw/placeholder payload)
+- richer QObject metaobject Ruby API (`meta_object`, methods/signatures/properties introspection)
+- normalize signal naming rules for overloads and deterministic connect behavior
+
+### Later
+
+- expand generated surface for additional Qt modules (network, sql, xml, etc.) using the same generator policy
+- packaging hardening for Linux/macOS (install/build paths, gem install reliability)
+- CI matrix for Ruby/Qt combinations and scope modes (`widgets`, `qobject`, `all`)
+- add performance checks for generator traversal and compile size/time regression tracking
+
+## Development
+
+```bash
+bundle exec rake test
+bundle exec rake compile
+bundle exec rake rubocop
+```
+
+### Test Environment Variables
+
+Tests force `QT_QPA_PLATFORM=offscreen` by default to avoid opening GUI windows.
+
+- `QT_QPA_PLATFORM_FORCE_XCB=true`
+  - override test default and run with `QT_QPA_PLATFORM=xcb` (real X11 backend)
+- `QT_RUBY_MANUAL_MODIFIERS=1`
+  - enable manual keyboard-modifier smoke test (`Ctrl/Shift` must be pressed during test window)
+
+Examples:
+
+```bash
+# default headless test run
+bundle exec rake test
+
+# run tests on xcb backend
+QT_QPA_PLATFORM_FORCE_XCB=true bundle exec rake test
+
+# run only manual modifiers smoke test
+QT_QPA_PLATFORM_FORCE_XCB=true QT_RUBY_MANUAL_MODIFIERS=1 \
+bundle exec ruby -Itest test/application_test.rb \
+  --name test_qapplication_keyboard_modifiers_manual_ctrl_shift_smoke --verbose
+```
+
+### Generation Scope
+
+Default build scope is `all`. You can still override scope manually with `QT_RUBY_SCOPE`:
+
+- `widgets` (default): QWidget/QLayout-oriented classes.
+- `qobject`: QObject descendants excluding QWidget/QLayout branch.
+- `all`: combined public surface from `widgets` + `qobject` scopes (default build mode).
+
+Examples:
+
+```bash
+QT_RUBY_SCOPE=widgets bundle exec rake compile
+QT_RUBY_SCOPE=qobject bundle exec rake compile
+QT_RUBY_SCOPE=all bundle exec rake compile
+```
+
+If Qt is in a custom prefix:
+
+```bash
+export PKG_CONFIG_PATH="/path/to/qt/lib/pkgconfig:$PKG_CONFIG_PATH"
+```
+
+Native event-runtime debug logs:
+
+```bash
+QT_RUBY_EVENT_DEBUG=1 ruby your_app.rb
+```
+
+Optional tuning:
+
+```bash
+# enable ancestor fallback for MouseMove events (off by default)
+QT_RUBY_EVENT_ANCESTOR_MOUSE_MOVE=1 ruby your_app.rb
+```

data/Rakefile

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'rake/clean'
+require 'rake/testtask'
+require 'rubygems'
+require 'rubocop/rake_task'
+
+CLEAN.include(
+  '**/*.o',
+  '**/*.so',
+  '**/*.bundle',
+  '**/*.dll',
+  '**/*.dylib',
+  'ext/**/Makefile',
+  'ext/**/mkmf.log',
+  'ext/**/.sitearchdir.time',
+  'ext/**/.sitelibdir.time',
+  'tmp',
+  'build'
+)
+
+EXT_DIR = File.expand_path('ext/qt_ruby_bridge', __dir__)
+NATIVE_BUILD_DIR = File.expand_path('build/native', __dir__)
+GENERATOR = File.expand_path('scripts/generate_bridge.rb', __dir__)
+GEMSPEC_PATH = File.expand_path('qt.gemspec', __dir__)
+GEM_SPEC = Gem::Specification.load(GEMSPEC_PATH)
+GEM_FILE = "#{GEM_SPEC.name}-#{GEM_SPEC.version}.gem".freeze
+PKG_DIR = File.expand_path('build/pkg', __dir__)
+PKG_FILE = File.join(PKG_DIR, GEM_FILE)
+GENERATED_CPP_PATH = File.expand_path('build/generated/qt_ruby_bridge.cpp', __dir__)
+NATIVE_CPP_PATH = File.join(NATIVE_BUILD_DIR, 'qt_ruby_bridge.cpp')
+
+desc 'Generate native bridge sources from system Qt headers'
+task :generate_bindings do
+  sh "QT_RUBY_SCOPE=all ruby #{GENERATOR}"
+end
+
+namespace :generate_bindings do
+  desc 'Generate bindings for widgets scope'
+  task :widgets do
+    sh "QT_RUBY_SCOPE=widgets ruby #{GENERATOR}"
+  end
+
+  desc 'Generate bindings for qobject scope'
+  task :qobject do
+    sh "QT_RUBY_SCOPE=qobject ruby #{GENERATOR}"
+  end
+
+  desc 'Generate bindings for all scope'
+  task :all do
+    sh "QT_RUBY_SCOPE=all ruby #{GENERATOR}"
+  end
+end
+
+desc 'Compile native Qt bridge'
+task compile: 'compile:all'
+
+def compile_for_scope(scope)
+  sh "mkdir -p #{NATIVE_BUILD_DIR}"
+  sh "cp #{GENERATED_CPP_PATH} #{NATIVE_CPP_PATH}"
+  sh({ 'QT_RUBY_SCOPE' => scope }, "ruby #{File.join(EXT_DIR, 'extconf.rb')}", chdir: NATIVE_BUILD_DIR)
+  sh 'make', chdir: NATIVE_BUILD_DIR
+  sh 'mkdir -p ../qt', chdir: NATIVE_BUILD_DIR
+  sh 'cp qt_ruby_bridge.so ../qt/qt_ruby_bridge.so', chdir: NATIVE_BUILD_DIR
+end
+
+namespace :compile do
+  %w[widgets qobject all].each do |scope|
+    desc "Compile native Qt bridge for #{scope} scope"
+    task scope.to_sym => "generate_bindings:#{scope}" do
+      compile_for_scope(scope)
+    end
+  end
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end
+
+desc 'Build gem package'
+task :build_gem do
+  sh "mkdir -p #{PKG_DIR}"
+  sh "gem build #{GEMSPEC_PATH} --output #{PKG_FILE}"
+end
+
+desc 'Install gem locally (build + gem install --local)'
+task install: :build_gem do
+  sh "gem install --local --force #{PKG_FILE}"
+end
+
+RuboCop::RakeTask.new(:rubocop)
+
+task default: :test

data/examples/development_ordered_demos/01_dsl_hello.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path('../../lib', __dir__))
+require 'qt'
+
+width = 640
+height = 360
+
+app = QApplication.new(0, [])
+
+window = QWidget.new do |w|
+  w.setWindowTitle('Qt Ruby App')
+  w.resize(width, height)
+end
+
+QLabel.new(window) do |l|
+  l.setText('Hello from Ruby')
+  l.setAlignment(Qt::AlignCenter)
+  l.setGeometry(0, 0, width, height)
+end
+
+exit(app.exec)

data/examples/development_ordered_demos/02_live_layout_console.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path('../../lib', __dir__))
+require 'qt'
+require 'irb'
+
+app = QApplication.new(0, [])
+window = QWidget.new do |w|
+  w.set_window_title('Qt Live Layout Console')
+  w.resize(700, 500)
+end
+
+layout = QVBoxLayout.new(window)
+window.set_layout(layout)
+
+items = []
+
+banner = QLabel.new(window) do |l|
+  l.set_text('Use IRB helpers: add_label, add_button, remove_last')
+  l.set_alignment(Qt::AlignCenter)
+end
+layout.add_widget(banner)
+items << banner
+
+jobs = Queue.new
+running = true
+
+console = Object.new
+console.instance_variable_set(:@app, app)
+console.instance_variable_set(:@window, window)
+console.instance_variable_set(:@layout, layout)
+console.instance_variable_set(:@jobs, jobs)
+console.instance_variable_set(:@items, items)
+
+console.define_singleton_method(:app) { @app }
+console.define_singleton_method(:window) { @window }
+console.define_singleton_method(:layout) { @layout }
+console.define_singleton_method(:items) { @items }
+
+console.define_singleton_method(:gui) do |&block|
+  raise ArgumentError, 'pass block to gui { ... }' unless block
+
+  reply = Queue.new
+  @jobs << [block, reply]
+  ok, value = reply.pop
+  raise value unless ok
+
+  value
+end
+
+console.define_singleton_method(:add_label) do |text = 'new label'|
+  gui do
+    label = QLabel.new(@window)
+    label.set_text(text)
+    label.set_alignment(Qt::AlignCenter)
+    @layout.add_widget(label)
+    @items << label
+    label
+  end
+end
+
+console.define_singleton_method(:add_button) do |text = 'new button'|
+  gui do
+    button = QPushButton.new(@window)
+    button.set_text(text)
+    @layout.add_widget(button)
+    @items << button
+    button
+  end
+end
+
+console.define_singleton_method(:remove_last) do
+  gui do
+    widget = @items.pop
+    if widget
+      @layout.remove_widget(widget)
+      widget.hide if widget.respond_to?(:hide)
+      widget
+    end
+  end
+end
+
+console.define_singleton_method(:help) do
+  puts 'Examples:'
+  puts '  add_label("Header")'
+  puts '  add_button("Run")'
+  puts '  remove_last'
+  puts '  gui { window.resize(900, 600) }'
+  puts '  items'
+  puts '  exit'
+end
+
+window.show
+QApplication.process_events
+
+puts 'Starting IRB with live layout editor.'
+puts 'Objects: app, window, layout, items'
+console.help
+
+irb_thread = Thread.new do
+  IRB.setup(nil)
+  workspace = IRB::WorkSpace.new(console.instance_eval { binding })
+  irb = IRB::Irb.new(workspace)
+  IRB.conf[:MAIN_CONTEXT] = irb.context
+
+  catch(:IRB_EXIT) { irb.eval_input }
+ensure
+  jobs << :__exit__
+end
+
+# TODO: Replace manual process_events polling with app.exec + QTimer-driven integration.
+while running
+  loop do
+    job = jobs.pop(true)
+
+    if job == :__exit__
+      running = false
+      break
+    end
+
+    block, reply = job
+    begin
+      reply << [true, block.call]
+    rescue StandardError => e
+      reply << [false, e]
+    end
+  rescue ThreadError
+    break
+  end
+
+  QApplication.process_events
+  running = false if window.is_visible.zero?
+  sleep(0.01)
+end
+
+irb_thread.kill if irb_thread&.alive?
+app.dispose