qt 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b772dc4333d9bfcf419388425980a833e99d5253bbab7d50a506dd886334153
-  data.tar.gz: 05133ee6f7bf9ad3a4ba582eb0f7bd214a1886005e7caa32939d5aa88c077f47
+  metadata.gz: b476ba2b95707fc32d1995f8ae8dfc5c8068ab46020e00ea5442b1fb42dd3220
+  data.tar.gz: 2ffb03be131be2c47d5d89f1094600d6e52fdb6891ffaabc40a3d8d7f6356c31
 SHA512:
-  metadata.gz: 97f0df292c1559e78a67b4075dbf8bfa35cb3804cb8720f2b0a5ea4a0f645b1b5f89108c076677dce1699a376225174df246d8316fe58466ffb53ab14cd18eb4
-  data.tar.gz: 2817088f7103798af9a8b6b71046cf8cf0570f4842265c18be8a4cfb3025c2e921b70e0ab95c1d6953137d7024b041496f4aeb331e0cf05cf2c57b73423c87d8
+  metadata.gz: 710c7df3d9c1950c14d35762a9223eb64cb4184573e0456fd864f5dd139f35224d03b144d0d121f465221e107e11a7c22e3053ee0b5508db72fe8e803ac3fc0c
+  data.tar.gz: b8424801d5f61607f02ad9fb48cc5e6941f4dc811a38c4dbb5439d2e9f5dc561ed1ed814ec910d9ae81e49d84bf47fd40957ecfee07bb951900c80567ba49789

data/LICENSE

@@ -1,5 +1,3 @@
-SPDX-License-Identifier: BSD-2-Clause
-
 BSD 2-Clause License
 
 Copyright (c) 2026, Maksim Veynberg

data/README.md

@@ -1,6 +1,6 @@
 # qt
 
-![Ruby](https://img.shields.io/badge/Ruby-3.1%2B-CC342D)
+![Ruby](https://img.shields.io/badge/Ruby-3.2%2B-CC342D)
 ![Qt](https://img.shields.io/badge/Qt-6.4.2%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)
@@ -9,7 +9,7 @@ Ruby-first Qt 6.4.2+ 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
+## Highlights
 
 - Pure Ruby usage: no QML, no extra UI language.
 - Real Qt power: `QApplication`, `QWidget`, `QLabel`, `QPushButton`, `QVBoxLayout`.
@@ -17,46 +17,25 @@ Build real Qt Widgets apps in pure Ruby, mutate them live from IRB, and keep C/C
 - 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
+## Install
 
-Before (typical static run):
+### Quick install (RubyGems)
 
-```ruby
-app = QApplication.new(0, [])
-window = QWidget.new
-window.show
-app.exec
+```bash
+gem install qt
 ```
 
-After (live dev loop):
+### Quick install (Fedora, binary RPM via COPR)
 
-```ruby
-# app already running
-add_label("Dynamic block")
-add_button("Ship")
-gui { window.set_window_title("Changed live") }
+```bash
+sudo dnf copr enable cyjimmy264/ruby-qt -y
+sudo dnf install -y ruby-qt
 ```
 
-## Install
+This installs a prebuilt package. Nothing is compiled on the target machine.
+Package name: `ruby-qt`.
 
-### Requirements
+### Requirements (build from source)
 
 - Ruby 3.2+
 - Qt 6.4.2+ dev packages (`Qt6Core`, `Qt6Gui`, `Qt6Widgets` via `pkg-config`)
@@ -94,10 +73,21 @@ 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
+## Quick Start
 
 ```bash
-gem install qt
+bundle exec ruby examples/development_ordered_demos/02_live_layout_console.rb
+```
+
+Optional: run interactive commands in IRB while the app is open:
+
+```ruby
+add_label("Release pipeline")
+add_button("Run")
+remove_last
+
+gui { window.resize(1100, 700) }
+items.last&.q_inspect
 ```
 
 ## Hello Qt in Ruby
@@ -184,10 +174,7 @@ Shape:
 
 ## Examples
 
-```bash
-ruby examples/development_ordered_demos/01_dsl_hello.rb
-ruby examples/development_ordered_demos/02_live_layout_console.rb
-```
+See all demos in [`examples/development_ordered_demos`](examples/development_ordered_demos).
 
 QObject signal example:
 
@@ -198,6 +185,10 @@ timer.connect('timeout') { puts 'tick' }
 timer.start
 ```
 
+## Projects
+
+- [`qtimetrap`](https://github.com/CyJimmy264/qtimetrap) - timetrap desktop UI built with this bridge.
+
 ## Architecture
 
 1. `scripts/generate_bridge.rb` reads Qt API from system headers.
@@ -253,8 +244,8 @@ Everything generated/build-related is under `build/` and should stay out of git.
 ## Development
 
 ```bash
-bundle exec rake test
 bundle exec rake compile
+bundle exec rake test
 bundle exec rake rubocop
 ```
 

data/lib/qt/object_wrapper.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Qt
+  # Wrap native QObject-derived pointers into generated Ruby wrapper instances.
+  module ObjectWrapper
+    module_function
+
+    def wrap(pointer, expected_qt_class = nil)
+      return nil if null_pointer?(pointer)
+      return pointer if pointer.respond_to?(:handle)
+
+      klass = resolve_wrapper_class(pointer, expected_qt_class) || fallback_wrapper_class(expected_qt_class)
+      return pointer unless klass
+
+      instantiate_wrapper(klass, pointer)
+    end
+
+    def null_pointer?(pointer)
+      pointer.nil? || (pointer.respond_to?(:null?) && pointer.null?)
+    end
+
+    def resolve_wrapper_class(pointer, expected_qt_class)
+      candidate_wrapper_classes(expected_qt_class).find do |klass|
+        Native.qobject_inherits(pointer, klass::QT_CLASS)
+      end
+    end
+
+    def candidate_wrapper_classes(expected_qt_class)
+      @candidate_wrapper_classes ||= {}
+      @candidate_wrapper_classes[expected_qt_class] ||= begin
+        base = fallback_wrapper_class(expected_qt_class)
+        wrappers = qobject_wrapper_classes
+        wrappers = wrappers.select { |klass| klass <= base } if base
+        wrappers.sort_by { |klass| -inheritance_depth(klass) }
+      end
+    end
+
+    def qobject_wrapper_classes
+      Qt.constants(false).filter_map do |const_name|
+        klass = Qt.const_get(const_name, false)
+        next unless klass.is_a?(Class)
+        next unless klass.const_defined?(:QT_CLASS, false)
+        next unless klass <= Qt::QObject
+
+        klass
+      end
+    end
+
+    def fallback_wrapper_class(expected_qt_class)
+      return nil if expected_qt_class.nil? || !Qt.const_defined?(expected_qt_class, false)
+
+      klass = Qt.const_get(expected_qt_class, false)
+      return nil unless klass.is_a?(Class)
+      return nil unless klass.const_defined?(:QT_CLASS, false)
+      return nil unless klass <= Qt::QObject
+
+      klass
+    end
+
+    def instantiate_wrapper(klass, pointer)
+      wrapped = klass.allocate
+      wrapped.instance_variable_set(:@handle, pointer)
+      wrapped.init_children_tracking! if wrapped.respond_to?(:init_children_tracking!, true)
+      wrapped
+    end
+
+    def inheritance_depth(klass)
+      depth = 0
+      current = klass
+      while current.is_a?(Class)
+        depth += 1
+        current = current.superclass
+      end
+      depth
+    end
+  end
+end

data/lib/qt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Qt
-  VERSION = '0.1.3'
+  VERSION = '0.1.4'
 end

data/lib/qt.rb

@@ -23,6 +23,7 @@ require_relative 'qt/key_sequence_codec'
 require_relative 'qt/variant_codec'
 require_relative 'qt/inspectable'
 require_relative 'qt/children_tracking'
+require_relative 'qt/object_wrapper'
 require_relative 'qt/application_lifecycle'
 require_relative 'qt/bridge'
 require_relative 'qt/native'

data/scripts/generate_bridge/auto_methods.rb

@@ -67,13 +67,13 @@ def normalized_cpp_type_name(type_name)
   type
 end
 
-def map_cpp_return_type(type_name)
+def map_cpp_return_type(type_name, ast: nil)
   raw = type_name.to_s.strip
   return nil if unsupported_cpp_type?(raw)
   return nil if raw.start_with?('const ') && raw.end_with?('*')
 
   type = raw.sub(/\Aconst\s+/, '').sub(/\s*&\z/, '').strip
-  map_scalar_cpp_return_type(type) || map_pointer_cpp_return_type(type)
+  map_scalar_cpp_return_type(type) || map_pointer_cpp_return_type(type, ast: ast)
 end
 
 def map_scalar_cpp_return_type(type)
@@ -89,10 +89,16 @@ def map_scalar_cpp_return_type(type)
   nil
 end
 
-def map_pointer_cpp_return_type(type)
-  return { ffi_return: :pointer } if type.end_with?('*')
+def map_pointer_cpp_return_type(type, ast: nil)
+  return nil unless type.end_with?('*')
 
-  nil
+  info = { ffi_return: :pointer }
+  base_type = type.sub(/\s*\*\z/, '').strip
+  if ast && class_inherits?(ast, base_type, 'QObject')
+    info[:pointer_class] = base_type
+  end
+
+  info
 end
 
 def parse_method_param_nodes(method_decl)
@@ -165,14 +171,15 @@ def build_auto_method_hash(entry, ret_info, args, required_arg_count)
     required_arg_count: required_arg_count
   }
   method[:return_cast] = ret_info[:return_cast] if ret_info[:return_cast]
+  method[:pointer_class] = ret_info[:pointer_class] if ret_info[:pointer_class]
   method
 end
 
-def build_auto_method_from_decl(method_decl, entry, qt_class:, int_cast_types:)
+def build_auto_method_from_decl(method_decl, entry, qt_class:, int_cast_types:, ast:)
   parsed = parse_method_signature(method_decl)
   return nil unless parsed
 
-  ret_info = map_cpp_return_type(parsed[:return_type])
+  ret_info = map_cpp_return_type(parsed[:return_type], ast: ast)
   return nil unless ret_info
 
   args, required_arg_count = build_auto_method_args(parsed, entry, qt_class, int_cast_types)
@@ -224,11 +231,11 @@ def invalid_method_name_scope?(class_name, visited)
   class_name.nil? || class_name.empty? || visited[class_name]
 end
 
-def build_auto_method_candidate(decl, entry, qt_class, int_cast_types)
+def build_auto_method_candidate(ast, decl, entry, qt_class, int_cast_types)
   parsed = parse_method_signature(decl)
   return nil unless parsed
 
-  method = build_auto_method_from_decl(decl, entry, qt_class: qt_class, int_cast_types: int_cast_types)
+  method = build_auto_method_from_decl(decl, entry, qt_class: qt_class, int_cast_types: int_cast_types, ast: ast)
   return nil unless method
 
   {
@@ -276,11 +283,11 @@ def resolve_auto_method_cache_key(qt_class, entry)
   ]
 end
 
-def build_auto_method_candidates(decls, entry, qt_class, int_cast_types)
+def build_auto_method_candidates(ast, decls, entry, qt_class, int_cast_types)
   decls.filter_map do |decl|
     next unless auto_method_decl_candidate?(decl)
 
-    build_auto_method_candidate(decl, entry, qt_class, int_cast_types)
+    build_auto_method_candidate(ast, decl, entry, qt_class, int_cast_types)
   end
 end
 
@@ -325,7 +332,7 @@ def resolve_auto_method_built_candidates(ast, qt_class, entry)
   return nil if decls.empty?
 
   int_cast_types = ast_int_cast_type_set(ast)
-  built = build_auto_method_candidates(decls, entry, qt_class, int_cast_types)
+  built = build_auto_method_candidates(ast, decls, entry, qt_class, int_cast_types)
   return nil if built.empty?
 
   built = filter_auto_method_candidates(built, entry)

data/scripts/generate_bridge/free_function_specs.rb

@@ -2,7 +2,7 @@
 
 RUNTIME_HEADER_PATH = File.expand_path('../../ext/qt_ruby_bridge/qt_ruby_runtime.hpp', __dir__)
 
-SCALAR_CLASS_METHOD_FFI_RETURNS = %i[void int bool string].freeze
+SCALAR_CLASS_METHOD_FFI_RETURNS = %i[void int bool string pointer].freeze
 QAPPLICATION_STATIC_METHOD_EXCLUSIONS = %w[exec].freeze
 QAPPLICATION_STATIC_TEXT_SETTERS = %w[
   setApplicationName
@@ -239,7 +239,8 @@ def build_qapplication_static_free_function_spec(ast, qt_name, int_cast_types)
       ruby_name: qt_name,
       native: native_name,
       args: [],
-      return_cast: candidate[:return_cast]
+      return_cast: candidate[:return_cast],
+      pointer_class: candidate[:pointer_class]
     }
   }
 end
@@ -253,7 +254,7 @@ def resolve_qapplication_static_noarg_candidate(ast, qt_name, int_cast_types)
     parsed = parse_method_signature(decl)
     next unless parsed && parsed[:required_arg_count].zero?
 
-    ret_info = qapplication_static_return_info(parsed[:return_type], int_cast_types)
+    ret_info = qapplication_static_return_info(parsed[:return_type], int_cast_types, ast: ast)
     next unless ret_info
 
     { decl: decl, param_count: parsed[:params].length }.merge(ret_info)
@@ -263,10 +264,15 @@ def resolve_qapplication_static_noarg_candidate(ast, qt_name, int_cast_types)
   candidates.min_by { |item| item[:param_count] }
 end
 
-def qapplication_static_return_info(return_type, int_cast_types)
-  mapped = map_cpp_return_type(return_type)
+def qapplication_static_return_info(return_type, int_cast_types, ast:)
+  mapped = map_cpp_return_type(return_type, ast: ast)
   if mapped && SCALAR_CLASS_METHOD_FFI_RETURNS.include?(mapped[:ffi_return])
-    return { ffi_return: mapped[:ffi_return], return_cast: mapped[:return_cast], enum_cast: false }
+    return {
+      ffi_return: mapped[:ffi_return],
+      return_cast: mapped[:return_cast],
+      pointer_class: mapped[:pointer_class],
+      enum_cast: false
+    }
   end
 
   normalized = normalized_cpp_type_name(return_type)

data/scripts/generate_bridge.rb

@@ -151,13 +151,13 @@ def find_getter_decl(ast, qt_class, property)
     parsed = parse_method_signature(decl)
     next false unless parsed && parsed[:params].empty?
 
-    map_cpp_return_type(parsed[:return_type])
+    map_cpp_return_type(parsed[:return_type], ast: ast)
   end
 end
 
-def build_property_getter_method(getter_decl, property)
+def build_property_getter_method(ast, getter_decl, property)
   parsed_getter = parse_method_signature(getter_decl)
-  ret_info = map_cpp_return_type(parsed_getter[:return_type])
+  ret_info = map_cpp_return_type(parsed_getter[:return_type], ast: ast)
   return nil unless ret_info
 
   getter = {
@@ -168,6 +168,7 @@ def build_property_getter_method(getter_decl, property)
     property: property
   }
   getter[:return_cast] = ret_info[:return_cast] if ret_info[:return_cast]
+  getter[:pointer_class] = ret_info[:pointer_class] if ret_info[:pointer_class]
   getter
 end
 
@@ -180,7 +181,7 @@ def enrich_spec_with_property_getter!(methods, ast, spec, method)
   getter_decl = find_getter_decl(ast, spec[:qt_class], property)
   return unless getter_decl
 
-  getter = build_property_getter_method(getter_decl, property)
+  getter = build_property_getter_method(ast, getter_decl, property)
   methods << getter if getter
 end
 
@@ -675,6 +676,7 @@ def ruby_native_method_body(method, rewritten_native_call)
   return "Qt::DateTimeCodec.decode_qdatetime(#{rewritten_native_call})" if method[:return_cast] == :qdatetime_to_utf8
   return "Qt::DateTimeCodec.decode_qdate(#{rewritten_native_call})" if method[:return_cast] == :qdate_to_utf8
   return "Qt::DateTimeCodec.decode_qtime(#{rewritten_native_call})" if method[:return_cast] == :qtime_to_utf8
+  return "Qt::ObjectWrapper.wrap(#{rewritten_native_call}, '#{method[:pointer_class]}')" if method[:pointer_class]
 
   rewritten_native_call
 end
@@ -824,6 +826,7 @@ def qapplication_class_method_body(method, native_call)
   return "        Qt::DateTimeCodec.decode_qdatetime(#{native_call})" if method[:return_cast] == :qdatetime_to_utf8
   return "        Qt::DateTimeCodec.decode_qdate(#{native_call})" if method[:return_cast] == :qdate_to_utf8
   return "        Qt::DateTimeCodec.decode_qtime(#{native_call})" if method[:return_cast] == :qtime_to_utf8
+  return "        Qt::ObjectWrapper.wrap(#{native_call}, '#{method[:pointer_class]}')" if method[:pointer_class]
 
   "        #{native_call}"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: qt
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Maksim Veynberg
@@ -61,6 +61,7 @@ files:
 - lib/qt/inspectable.rb
 - lib/qt/key_sequence_codec.rb
 - lib/qt/native.rb
+- lib/qt/object_wrapper.rb
 - lib/qt/shortcut_compat.rb
 - lib/qt/string_codec.rb
 - lib/qt/variant_codec.rb