qt 0.1.3 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b772dc4333d9bfcf419388425980a833e99d5253bbab7d50a506dd886334153
-  data.tar.gz: 05133ee6f7bf9ad3a4ba582eb0f7bd214a1886005e7caa32939d5aa88c077f47
+  metadata.gz: 58b685a5934b6ab65de8085da77093cf9de7b608a2f047638e6662ece29f4f8a
+  data.tar.gz: 3ce44932b8d818b1068908d73189704bdd4b1e2f54e6d2e462c83d217b81c3f3
 SHA512:
-  metadata.gz: 97f0df292c1559e78a67b4075dbf8bfa35cb3804cb8720f2b0a5ea4a0f645b1b5f89108c076677dce1699a376225174df246d8316fe58466ffb53ab14cd18eb4
-  data.tar.gz: 2817088f7103798af9a8b6b71046cf8cf0570f4842265c18be8a4cfb3025c2e921b70e0ab95c1d6953137d7024b041496f4aeb331e0cf05cf2c57b73423c87d8
+  metadata.gz: aac76dc37741b86a72be2b8b5f1d671b3f0e4fc59ad95e2958264c7a9929f3dad7d445e3bded8f46d67bc304296b0610d7f427ca19eebaec99fd41dff4d454cb
+  data.tar.gz: 50d80970f96868a576ac445b84bbf45ea002bf8c55038b52d3e0c1f2a522d89c6cf2e2120a895b43963cc912900ab63a3520be8d91278d3a8f5a6ec08e364569

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/ext/qt_ruby_bridge/qt_ruby_runtime.hpp

@@ -3,7 +3,7 @@
 #include <QApplication>
 
 namespace QtRubyRuntime {
-using EventCallback = void (*)(void*, int, int, int, int, int);
+using EventCallback = int (*)(void*, int, const char*);
 using SignalCallback = void (*)(void*, int, const char*);
 
 // Creates/owns the singleton QApplication used by the Ruby runtime bridge.

data/ext/qt_ruby_bridge/runtime_events.cpp

@@ -1,15 +1,11 @@
 #include "qt_ruby_runtime.hpp"
 
 #include <QApplication>
+#include <QByteArray>
 #include <QCoreApplication>
 #include <QEvent>
 #include <QEventLoop>
-#include <QKeyEvent>
-#include <QMouseEvent>
 #include <QObject>
-#include <QPoint>
-#include <QResizeEvent>
-#include <QByteArray>
 #include <QWidget>
 #include <cstdio>
 #include <cstdlib>
@@ -17,7 +13,13 @@
 #include <unordered_map>
 #include <unordered_set>
 
+#include "../../build/generated/event_payloads.inc"
+
 namespace QtRubyRuntime {
+constexpr int kEventCallbackIgnore = 0;
+constexpr int kEventCallbackContinue = 1;
+constexpr int kEventCallbackConsume = 2;
+
 EventCallback& event_callback_ref() {
   static EventCallback callback = nullptr;
   return callback;
@@ -117,6 +119,8 @@ const char* event_name(int et) {
       return "Leave";
     case QEvent::Resize:
       return "Resize";
+    case QEvent::Wheel:
+      return "Wheel";
     default:
       return "Other";
   }
@@ -161,6 +165,7 @@ bool supports_ancestor_dispatch(int event_type) {
     case QEvent::FocusOut:
     case QEvent::Enter:
     case QEvent::Leave:
+    case QEvent::Wheel:
       return true;
     default:
       return false;
@@ -219,46 +224,16 @@ class EventFilter : public QObject {
       return QObject::eventFilter(watched, event);
     }
 
-    int a = 0;
-    int b = 0;
-    int c = 0;
-    int d = 0;
-
-    switch (event->type()) {
-      case QEvent::MouseButtonPress:
-      case QEvent::MouseButtonRelease:
-      case QEvent::MouseMove: {
-        auto* mouse_event = static_cast<QMouseEvent*>(event);
-        const QPoint p = mouse_event->position().toPoint();
-        a = p.x();
-        b = p.y();
-        c = static_cast<int>(mouse_event->button());
-        d = static_cast<int>(mouse_event->buttons());
-        break;
-      }
-      case QEvent::KeyPress:
-      case QEvent::KeyRelease: {
-        auto* key_event = static_cast<QKeyEvent*>(event);
-        a = key_event->key();
-        b = static_cast<int>(key_event->modifiers());
-        c = key_event->isAutoRepeat() ? 1 : 0;
-        d = key_event->count();
-        break;
-      }
-      case QEvent::Resize: {
-        auto* resize_event = static_cast<QResizeEvent*>(event);
-        a = resize_event->size().width();
-        b = resize_event->size().height();
-        c = resize_event->oldSize().width();
-        d = resize_event->oldSize().height();
-        break;
-      }
-      default:
-        break;
-    }
-
+    const QByteArray payload_json = QtRubyGeneratedEventPayloads::serialize_event_payload(et, event);
     log_event_dispatch(watched, dispatch_target, et, event->isAccepted(), "dispatch");
-    event_callback_ref()(dispatch_target, et, a, b, c, d);
+    const int callback_result = event_callback_ref()(dispatch_target, et, payload_json.constData());
+    if (callback_result == kEventCallbackIgnore) {
+      event->ignore();
+    }
+    if (callback_result == kEventCallbackConsume) {
+      event->accept();
+      return true;
+    }
     return QObject::eventFilter(watched, event);
   }
 };

data/lib/qt/event_runtime.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module Qt
   # Event/signal subscription runtime backed by generated native callbacks.
   module EventRuntime
@@ -77,13 +79,7 @@ module Qt
 
     def event_type_for(event_name)
       key = event_name.to_sym
-      map = {
-        mouse_button_press: Qt::EventMouseButtonPress, mouse_button_release: Qt::EventMouseButtonRelease,
-        mouse_move: Qt::EventMouseMove, key_press: Qt::EventKeyPress, key_release: Qt::EventKeyRelease,
-        focus_in: Qt::EventFocusIn, focus_out: Qt::EventFocusOut, enter: Qt::EventEnter,
-        leave: Qt::EventLeave, resize: Qt::EventResize
-      }
-      event_type = map[key]
+      event_type = Qt::GENERATED_EVENT_TYPES[key]
       raise ArgumentError, "unknown event: #{event_name.inspect}" unless event_type
 
       event_type
@@ -93,10 +89,9 @@ module Qt
       return if @event_callback
 
       @event_callback = FFI::Function.new(
-        :void, %i[pointer int int int int int]
-      ) do |object_handle, event_type, *args|
-        a, b, c, d = args
-        payload = { type: event_type, a: a, b: b, c: c, d: d }
+        :int, %i[pointer int string]
+      ) do |object_handle, event_type, payload_json|
+        payload = decode_event_payload(event_type, payload_json)
         EventRuntimeDispatch.dispatch_event(@event_handlers, object_handle, event_type, payload)
       end
 
@@ -120,6 +115,17 @@ module Qt
       widget.respond_to?(:handle) ? widget.handle : widget
     end
 
+    def decode_event_payload(event_type, payload_json)
+      payload =
+        if payload_json.nil? || payload_json.empty?
+          {}
+        else
+          JSON.parse(Qt::StringCodec.from_qt_text(payload_json), symbolize_names: true)
+        end
+      payload[:type] ||= event_type
+      payload
+    end
+
     def ensure_native_bridge_ready!
       Qt::Native.ensure_loaded!
       Qt::Native.define_bridge_wrappers!

data/lib/qt/event_runtime_dispatch.rb

@@ -4,18 +4,26 @@
 module Qt
   # Dispatch helpers for event/signal callbacks from the native bridge.
   module EventRuntimeDispatch
+    EVENT_RESULT_IGNORE = 0
+    EVENT_RESULT_CONTINUE = 1
+    EVENT_RESULT_CONSUME = 2
+
     module_function
 
     def dispatch_event(event_handlers, object_handle, event_type, payload)
-      return unless object_handle && event_handlers
+      return EVENT_RESULT_CONTINUE unless object_handle && event_handlers
 
       per_widget = event_handlers[object_handle.address]
-      return unless per_widget
+      return EVENT_RESULT_CONTINUE unless per_widget
 
       handlers = per_widget[event_type]
-      return unless handlers && !handlers.empty?
+      return EVENT_RESULT_CONTINUE unless handlers && !handlers.empty?
+
+      results = handlers.map { |handler| handler.call(payload) }
+      return EVENT_RESULT_CONSUME if results.any? { |result| result == true || result == :consume }
+      return EVENT_RESULT_IGNORE if results.any? { |result| result == false || result == :ignore }
 
-      handlers.each { |handler| handler.call(payload) }
+      EVENT_RESULT_CONTINUE
     end
 
     def dispatch_signal(signal_handlers, object_handle, signal_index, payload)

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.6'
 end

data/lib/qt.rb

@@ -8,8 +8,10 @@ GENERATED_DIR = File.join(ROOT, 'build', 'generated')
 GENERATED_WIDGETS = File.join(GENERATED_DIR, 'widgets.rb')
 GENERATED_API = File.join(GENERATED_DIR, 'bridge_api.rb')
 GENERATED_CONSTANTS = File.join(GENERATED_DIR, 'constants.rb')
+GENERATED_EVENT_PAYLOADS = File.join(GENERATED_DIR, 'event_payloads.rb')
 
-unless File.exist?(GENERATED_WIDGETS) && File.exist?(GENERATED_API) && File.exist?(GENERATED_CONSTANTS)
+unless File.exist?(GENERATED_WIDGETS) && File.exist?(GENERATED_API) && File.exist?(GENERATED_CONSTANTS) &&
+       File.exist?(GENERATED_EVENT_PAYLOADS)
   ok = system(RbConfig.ruby, GENERATOR)
   raise 'Failed to generate Qt Ruby bindings. Run: bundle exec rake compile' unless ok
 end
@@ -23,12 +25,14 @@ 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'
 require_relative 'qt/event_runtime_dispatch'
 require_relative 'qt/event_runtime_qobject_methods'
 require_relative 'qt/event_runtime'
+require GENERATED_EVENT_PAYLOADS
 require GENERATED_WIDGETS
 require_relative 'qt/shortcut_compat'
 Qt::GeneratedConstantsRuntime.apply_generated_scoped_constants!(Qt)

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/event_payloads.rb

@@ -0,0 +1,341 @@
+# frozen_string_literal: true
+
+EVENT_PAYLOAD_COMPATIBILITY_ALIASES = {
+  'QMouseEvent' => { a: :x, b: :y, c: :button, d: :buttons },
+  'QKeyEvent' => { a: :key, b: :modifiers, c: :is_auto_repeat, d: :count },
+  'QResizeEvent' => { a: :width, b: :height, c: :old_width, d: :old_height },
+  'QWheelEvent' => { a: :pixel_delta_y, b: :angle_delta_y, c: :buttons, d: nil }
+}.freeze
+
+EVENT_PAYLOAD_EXCLUDED_METHODS = %w[
+  accepted clone ignore isAccepted registerEventType setAccepted spontaneous type
+].freeze
+
+EVENT_PAYLOAD_SUPPORTED_COMPLEX_TYPES = %w[QPoint QPointF QSize].freeze
+
+def event_payload_class_names(ast)
+  @event_payload_class_names ||= {}.compare_by_identity
+  return @event_payload_class_names[ast] if @event_payload_class_names.key?(ast)
+
+  index = ast_class_index(ast)
+  @event_payload_class_names[ast] = index[:methods_by_class].keys.select do |class_name|
+    class_name.start_with?('Q') && class_name.end_with?('Event') && class_inherits?(ast, class_name, 'QEvent')
+  end.sort
+end
+
+def event_payload_ctor_type_param?(ctor_decl)
+  Array(ctor_decl['inner']).any? do |node|
+    next false unless node['kind'] == 'ParmVarDecl'
+
+    raw_type = node.dig('type', 'desugaredQualType') || node.dig('type', 'qualType')
+    name = node['name']
+    %w[type t].include?(name) && %w[Type QEvent::Type].include?(raw_type)
+  end
+end
+
+def event_payload_type_family_class_names(ast)
+  @event_payload_type_family_class_names ||= {}.compare_by_identity
+  return @event_payload_type_family_class_names[ast] if @event_payload_type_family_class_names.key?(ast)
+
+  @event_payload_type_family_class_names[ast] = event_payload_class_names(ast).select do |class_name|
+    collect_constructor_decls(ast, class_name).any? { |decl| event_payload_ctor_type_param?(decl) }
+  end
+end
+
+def event_payload_class_stem(class_name)
+  class_name.sub(/\AQ/, '').sub(/Event\z/, '')
+end
+
+def event_payload_camel_tokens(name)
+  name.to_s.scan(/[A-Z]+(?=[A-Z][a-z]|\z)|[A-Z]?[a-z]+|\d+/)
+end
+
+def event_payload_token_sequence_present?(haystack, needle)
+  return false if haystack.empty? || needle.empty? || needle.length > haystack.length
+
+  0.upto(haystack.length - needle.length).any? do |start_idx|
+    haystack[start_idx, needle.length] == needle
+  end
+end
+
+def event_payload_family_match?(event_name, class_name, mode)
+  event_tokens = event_payload_camel_tokens(event_name)
+  class_tokens = event_payload_camel_tokens(event_payload_class_stem(class_name))
+  return false if event_tokens.empty? || class_tokens.empty?
+
+  event_downcase = event_tokens.map(&:downcase)
+  class_downcase = class_tokens.map(&:downcase)
+  event_compact = event_downcase.join
+  class_compact = class_downcase.join
+
+  case mode
+  when :prefix
+    event_downcase.first(class_downcase.length) == class_downcase
+  when :suffix
+    event_downcase.last(class_downcase.length) == class_downcase
+  when :contiguous_tokens
+    event_payload_token_sequence_present?(event_downcase, class_downcase)
+  when :compact_substring
+    event_compact.include?(class_compact)
+  else
+    false
+  end
+end
+
+def event_payload_most_specific_class_names(ast, class_names)
+  class_names.reject do |class_name|
+    class_names.any? do |other|
+      next false if other == class_name
+
+      class_inherits?(ast, other, class_name)
+    end
+  end
+end
+
+def event_payload_longest_stem_class_names(class_names)
+  stems = class_names.to_h do |class_name|
+    [class_name, event_payload_camel_tokens(event_payload_class_stem(class_name)).length]
+  end
+  longest = stems.values.max
+  class_names.select { |class_name| stems[class_name] == longest }
+end
+
+def resolve_event_payload_family_class_name(ast, event_name, warnings)
+  %i[prefix suffix contiguous_tokens compact_substring].each do |mode|
+    matches = event_payload_type_family_class_names(ast).select do |class_name|
+      event_payload_family_match?(event_name, class_name, mode)
+    end
+    next if matches.empty?
+
+    matches = event_payload_most_specific_class_names(ast, matches)
+    matches = event_payload_longest_stem_class_names(matches)
+    return matches.first if matches.length == 1
+
+    warnings << "Qt::EventPayload: ambiguous #{mode} family match for #{event_name}: #{matches.sort.join(', ')}"
+    return nil
+  end
+
+  nil
+end
+
+def resolve_event_payload_class_name(ast, event_name, warnings = [])
+  exact_class_name = "Q#{event_name}Event"
+  return exact_class_name if event_payload_class_names(ast).include?(exact_class_name)
+
+  resolve_event_payload_family_class_name(ast, event_name, warnings)
+end
+
+def supported_event_payload_return?(return_type, int_cast_types)
+  return true if event_payload_scalar_return?(return_type, int_cast_types)
+  return true if EVENT_PAYLOAD_SUPPORTED_COMPLEX_TYPES.include?(normalized_cpp_type_name(return_type))
+
+  false
+end
+
+def event_payload_scalar_return?(return_type, int_cast_types)
+  raw = return_type.to_s.strip
+  return true if %w[bool int QString double float].include?(normalized_cpp_type_name(raw))
+
+  compact = raw.sub(/\Aconst\s+/, '').sub(/\s*&\z/, '').strip
+  compact.include?('::') && int_cast_types.include?(compact)
+end
+
+def event_payload_method_decl(ast, class_name, method_name, int_cast_types)
+  collect_method_decls_with_bases(ast, class_name, method_name).find do |decl|
+    next false unless decl['__effective_access'] == 'public'
+    next false if deprecated_method_decl?(decl)
+
+    parsed = parse_method_signature(decl)
+    next false unless parsed && parsed[:params].empty?
+    next false if EVENT_PAYLOAD_EXCLUDED_METHODS.include?(method_name)
+
+    supported_event_payload_return?(parsed[:return_type], int_cast_types)
+  end
+end
+
+def event_payload_method_candidates(ast, class_name, int_cast_types)
+  collect_method_names_with_bases(ast, class_name).sort.filter_map do |method_name|
+    decl = event_payload_method_decl(ast, class_name, method_name, int_cast_types)
+    next unless decl
+
+    parsed = parse_method_signature(decl)
+    { method_name: method_name, return_type: parsed[:return_type] }
+  end
+end
+
+def event_payload_base_name(method_name, return_type)
+  normalized = normalized_cpp_type_name(return_type)
+  snake = to_snake(method_name)
+  return '' if %w[QPoint QPointF].include?(normalized) && %w[position pos local_pos].include?(snake)
+  return 'global_' if %w[QPoint QPointF].include?(normalized) && %w[global_position global_pos].include?(snake)
+  return '' if normalized == 'QSize' && snake == 'size'
+  return 'old_' if normalized == 'QSize' && snake == 'old_size'
+
+  "#{snake}_"
+end
+
+def event_payload_fields_for_method(method_name, return_type, int_cast_types)
+  normalized = normalized_cpp_type_name(return_type)
+  base_name = event_payload_base_name(method_name, return_type)
+  getter = "typed_event->#{method_name}()"
+
+  case normalized
+  when 'bool'
+    [{ name: to_snake(method_name), cpp_expr: getter, json_type: :bool }]
+  when 'int'
+    [{ name: to_snake(method_name), cpp_expr: getter, json_type: :int }]
+  when 'QString'
+    [{ name: to_snake(method_name), cpp_expr: getter, json_type: :string }]
+  when 'double', 'float'
+    [{ name: to_snake(method_name), cpp_expr: getter, json_type: :float }]
+  when 'QPoint'
+    [
+      { name: "#{base_name}x", cpp_expr: "#{getter}.x()", json_type: :int },
+      { name: "#{base_name}y", cpp_expr: "#{getter}.y()", json_type: :int }
+    ]
+  when 'QPointF'
+    [
+      { name: "#{base_name}x", cpp_expr: "#{getter}.x()", json_type: :float },
+      { name: "#{base_name}y", cpp_expr: "#{getter}.y()", json_type: :float }
+    ]
+  when 'QSize'
+    [
+      { name: "#{base_name}width", cpp_expr: "#{getter}.width()", json_type: :int },
+      { name: "#{base_name}height", cpp_expr: "#{getter}.height()", json_type: :int }
+    ]
+  else
+    compact = return_type.to_s.sub(/\Aconst\s+/, '').sub(/\s*&\z/, '').strip
+    return [] unless compact.include?('::') && int_cast_types.include?(compact)
+
+    [{ name: to_snake(method_name), cpp_expr: "static_cast<int>(#{getter})", json_type: :int }]
+  end
+end
+
+def event_payload_compatibility_fields(class_name, field_names)
+  aliases = EVENT_PAYLOAD_COMPATIBILITY_ALIASES[class_name] || {}
+  aliases.each_with_object([]) do |(alias_name, target_name), out|
+    if target_name.nil?
+      out << { name: alias_name.to_s, source: nil, json_type: :int }
+      next
+    end
+
+    next unless field_names.include?(target_name.to_s)
+
+    out << { name: alias_name.to_s, source: target_name.to_s, json_type: :alias }
+  end
+end
+
+def collect_event_payload_schema_for(ast, event_name, event_value, int_cast_types, warnings)
+  class_name = resolve_event_payload_class_name(ast, event_name, warnings)
+  return nil if class_name.nil?
+  return nil unless ast_class_index(ast)[:methods_by_class].key?(class_name)
+
+  field_specs = event_payload_method_candidates(ast, class_name, int_cast_types).flat_map do |entry|
+    event_payload_fields_for_method(entry[:method_name], entry[:return_type], int_cast_types)
+  end
+  field_specs.uniq! { |field| field[:name] }
+
+  compatibility_fields = event_payload_compatibility_fields(class_name, field_specs.map { |field| field[:name] })
+  schema = {
+    symbol_name: qevent_symbol_name(event_name),
+    event_name: event_name,
+    event_value: event_value,
+    constant_name: "Event#{event_name}",
+    class_name: class_name,
+    fields: field_specs,
+    compatibility_fields: compatibility_fields
+  }
+
+  if field_specs.empty? && compatibility_fields.empty?
+    warnings << "Qt::EventPayload: #{event_name} resolved to #{class_name} but no payload fields were derived"
+  end
+
+  schema
+end
+
+def collect_event_payload_schemas(ast, warnings = [])
+  int_cast_types = ast_int_cast_type_set(ast)
+  collect_enum_constants_for_scope(ast, ['QEvent'], warnings).sort.filter_map do |event_name, event_value|
+    collect_event_payload_schema_for(ast, event_name, event_value, int_cast_types, warnings)
+  end
+end
+
+def generate_ruby_event_payloads(ast)
+  warnings = []
+  schemas = collect_event_payload_schemas(ast, warnings)
+  emit_generation_warnings(warnings)
+
+  lines = ['# frozen_string_literal: true', '', 'module Qt']
+  lines << '  GENERATED_EVENT_PAYLOAD_SCHEMAS = {'
+  schemas.each do |schema|
+    lines << "    #{schema[:symbol_name].inspect} => {"
+    lines << "      event_type: #{schema[:constant_name]},"
+    lines << "      event_class: '#{schema[:class_name]}',"
+    lines << '      fields: ['
+    schema[:fields].each do |field|
+      lines << "        { name: #{field[:name].inspect}, type: #{field[:json_type].inspect} },"
+    end
+    schema[:compatibility_fields].each do |field|
+      lines << "        { name: #{field[:name].inspect}, type: #{field[:json_type].inspect} },"
+    end
+    lines << '      ]'
+    lines << '    },'
+  end
+  lines << '  }.freeze unless const_defined?(:GENERATED_EVENT_PAYLOAD_SCHEMAS, false)'
+  lines << 'end'
+  "#{lines.join("\n")}\n"
+end
+
+def cpp_json_insert_lines(field, source_expr = nil)
+  expr = source_expr || field[:cpp_expr]
+  case field[:json_type]
+  when :bool, :int, :float
+    ["payload.insert(\"#{field[:name]}\", #{expr});"]
+  when :string
+    ["payload.insert(\"#{field[:name]}\", #{expr});"]
+  else
+    []
+  end
+end
+
+def generate_cpp_event_payload_extractor(ast)
+  warnings = []
+  schemas = collect_event_payload_schemas(ast, warnings)
+  emit_generation_warnings(warnings)
+
+  includes = schemas.map { |schema| "#include <#{schema[:class_name]}>" }.uniq.sort
+  lines = []
+  lines.concat(includes)
+  lines << '#include <QEvent>'
+  lines << '#include <QJsonDocument>'
+  lines << '#include <QJsonObject>'
+  lines << ''
+  lines << 'namespace QtRubyGeneratedEventPayloads {'
+  lines << 'inline QByteArray serialize_event_payload(int event_type, QEvent* event) {'
+  lines << '  QJsonObject payload;'
+  lines << '  payload.insert("type", event_type);'
+  lines << '  switch (static_cast<QEvent::Type>(event_type)) {'
+  schemas.each do |schema|
+    lines << "    case QEvent::#{schema[:event_name]}: {"
+    lines << "      auto* typed_event = static_cast<#{schema[:class_name]}*>(event);"
+    schema[:fields].each do |field|
+      cpp_json_insert_lines(field).each { |line| lines << "      #{line}" }
+    end
+    schema[:compatibility_fields].each do |field|
+      if field[:source]
+        lines << "      payload.insert(\"#{field[:name]}\", payload.value(\"#{field[:source]}\"));"
+      else
+        lines << "      payload.insert(\"#{field[:name]}\", 0);"
+      end
+    end
+    lines << '      break;'
+    lines << '    }'
+  end
+  lines << '    default:'
+  lines << '      break;'
+  lines << '  }'
+  lines << '  return QJsonDocument(payload).toJson(QJsonDocument::Compact);'
+  lines << '}'
+  lines << '}  // namespace QtRubyGeneratedEventPayloads'
+  "#{lines.join("\n")}\n"
+end

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

@@ -13,6 +13,8 @@ CPP_PATH = File.join(GENERATED_DIR, 'qt_ruby_bridge.cpp')
 API_PATH = File.join(GENERATED_DIR, 'bridge_api.rb')
 RUBY_WIDGETS_PATH = File.join(GENERATED_DIR, 'widgets.rb')
 RUBY_CONSTANTS_PATH = File.join(GENERATED_DIR, 'constants.rb')
+RUBY_EVENT_PAYLOADS_PATH = File.join(GENERATED_DIR, 'event_payloads.rb')
+CPP_EVENT_PAYLOADS_PATH = File.join(GENERATED_DIR, 'event_payloads.inc')
 
 # Universal generation policy: class set is discovered from AST per scope.
 GENERATOR_SCOPE = (ENV['QT_RUBY_SCOPE'] || 'all').freeze
@@ -50,6 +52,7 @@ require_relative 'generate_bridge/auto_method_spec_resolver'
 require_relative 'generate_bridge/cpp_method_return_emitter'
 require_relative 'generate_bridge/ast_introspection'
 require_relative 'generate_bridge/auto_methods'
+require_relative 'generate_bridge/event_payloads'
 require_relative 'generate_bridge/spec_discovery'
 
 def next_trace_base(fetch_bases, cur, visited)
@@ -151,13 +154,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 +171,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 +184,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 +679,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 +829,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
@@ -1014,6 +1020,30 @@ def collect_qt_namespace_enum_constants(ast, warnings = [])
   constants
 end
 
+def qevent_symbol_name(name)
+  to_snake(name).to_sym
+end
+
+def collect_qevent_symbol_map(ast, warnings = [])
+  symbol_map = {}
+
+  collect_enum_constants_for_scope(ast, ['QEvent'], warnings).each do |name, value|
+    symbol_name = qevent_symbol_name(name)
+    existing = symbol_map[symbol_name]
+    if existing.nil?
+      symbol_map[symbol_name] = { constant_name: "Event#{name}", value: value }
+      next
+    end
+
+    next if existing[:value] == value && existing[:constant_name] == "Event#{name}"
+
+    warnings << "Qt::QEventSymbolMap: #{symbol_name}=Event#{name}(#{value}) conflicts with existing " \
+                "#{existing[:constant_name]}(#{existing[:value]}); keeping existing #{existing[:constant_name]}"
+  end
+
+  symbol_map
+end
+
 def collect_qt_scoped_enum_constants(ast, warnings = [])
   constants_by_owner = Hash.new { |h, k| h[k] = {} }
 
@@ -1056,6 +1086,7 @@ def generate_ruby_constants(ast)
   warnings = []
   constants = collect_qt_namespace_enum_constants(ast, warnings)
   scoped_constants = collect_qt_scoped_enum_constants(ast, warnings)
+  event_symbol_map = collect_qevent_symbol_map(ast, warnings)
   emit_generation_warnings(warnings)
   lines = ['# frozen_string_literal: true', '', 'module Qt']
 
@@ -1073,6 +1104,12 @@ def generate_ruby_constants(ast)
     lines << '    },'
   end
   lines << '  }.freeze unless const_defined?(:GENERATED_SCOPED_CONSTANTS, false)'
+  lines << ''
+  lines << '  GENERATED_EVENT_TYPES = {'
+  event_symbol_map.sort.each do |symbol_name, entry|
+    lines << "    #{symbol_name.inspect} => #{entry[:constant_name]},"
+  end
+  lines << '  }.freeze unless const_defined?(:GENERATED_EVENT_TYPES, false)'
 
   lines << 'end'
   "#{lines.join("\n")}\n"
@@ -1101,6 +1138,14 @@ timed('write_ruby_constants') do
   FileUtils.mkdir_p(File.dirname(RUBY_CONSTANTS_PATH))
   File.write(RUBY_CONSTANTS_PATH, generate_ruby_constants(ast))
 end
+timed('write_ruby_event_payloads') do
+  FileUtils.mkdir_p(File.dirname(RUBY_EVENT_PAYLOADS_PATH))
+  File.write(RUBY_EVENT_PAYLOADS_PATH, generate_ruby_event_payloads(ast))
+end
+timed('write_cpp_event_payloads') do
+  FileUtils.mkdir_p(File.dirname(CPP_EVENT_PAYLOADS_PATH))
+  File.write(CPP_EVENT_PAYLOADS_PATH, generate_cpp_event_payload_extractor(ast))
+end
 timed('write_ruby_widgets') do
   FileUtils.mkdir_p(File.dirname(RUBY_WIDGETS_PATH))
   File.write(RUBY_WIDGETS_PATH, generate_ruby_widgets(effective_specs, super_qt_by_qt, wrapper_qt_classes))
@@ -1110,4 +1155,6 @@ debug_log("total=#{format('%.3fs', monotonic_now - total_start)}")
 puts "Generated #{CPP_PATH}"
 puts "Generated #{API_PATH}"
 puts "Generated #{RUBY_CONSTANTS_PATH}"
+puts "Generated #{RUBY_EVENT_PAYLOADS_PATH}"
+puts "Generated #{CPP_EVENT_PAYLOADS_PATH}"
 puts "Generated #{RUBY_WIDGETS_PATH}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: qt
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.6
 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
@@ -71,6 +72,7 @@ files:
 - scripts/generate_bridge/auto_methods.rb
 - scripts/generate_bridge/core_utils.rb
 - scripts/generate_bridge/cpp_method_return_emitter.rb
+- scripts/generate_bridge/event_payloads.rb
 - scripts/generate_bridge/ffi_api.rb
 - scripts/generate_bridge/free_function_specs.rb
 - scripts/generate_bridge/spec_discovery.rb
@@ -79,7 +81,7 @@ licenses:
 - BSD-2-Clause
 metadata:
   source_code_uri: https://github.com/CyJimmy264/qt
-  changelog_uri: https://github.com/CyJimmy264/qt/releases
+  changelog_uri: https://github.com/CyJimmy264/qt/blob/master/CHANGELOG.md
   bug_tracker_uri: https://github.com/CyJimmy264/qt/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []