qt 0.1.0

data/lib/qt/bridge.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'ffi'
+require 'rbconfig'
+
+module Qt
+  # Bridge helpers for registering and disposing wrapped native objects.
+  module Bridge
+    extend FFI::Library
+
+    module_function
+
+    def load!
+      return true if @loaded
+
+      ffi_lib(library_candidates)
+      attach_api
+      @loaded = true
+    rescue LoadError, FFI::NotFoundError => e
+      @loaded = false
+      @load_error = e
+      false
+    end
+
+    def loaded?
+      !!@loaded
+    end
+
+    def load_error
+      @load_error
+    end
+
+    def library_candidates
+      @library_candidates ||= begin
+        ext = RbConfig::CONFIG['DLEXT']
+        root = File.expand_path('../..', __dir__)
+        load_path_candidates = load_path_library_candidates(ext)
+        gem_extension_candidates = gem_extension_library_candidates(ext)
+
+        [
+          File.join(root, 'build', 'qt', "qt_ruby_bridge.#{ext}"),
+          File.join(root, 'lib', 'qt', "qt_ruby_bridge.#{ext}"),
+          *gem_extension_candidates,
+          *load_path_candidates,
+          'qt_ruby_bridge'
+        ].uniq
+      end
+    end
+
+    def load_path_library_candidates(ext)
+      $LOAD_PATH.flat_map do |entry|
+        [
+          File.join(entry, 'qt', "qt_ruby_bridge.#{ext}"),
+          File.join(entry, "qt_ruby_bridge.#{ext}")
+        ]
+      end
+    end
+
+    def gem_extension_library_candidates(ext)
+      spec = Gem::Specification.find_by_name('qt')
+      extension_dir = spec&.extension_dir
+      return [] if extension_dir.nil? || extension_dir.empty?
+
+      [
+        File.join(extension_dir, 'qt', "qt_ruby_bridge.#{ext}"),
+        File.join(extension_dir, "qt_ruby_bridge.#{ext}")
+      ]
+    rescue Gem::LoadError
+      []
+    end
+
+    def attach_api
+      return if @api_attached
+
+      ensure_generated_api!
+      Qt::BridgeAPI::FUNCTIONS.each do |fn|
+        attach_function fn[:name], fn[:args], fn[:return]
+      end
+
+      @api_attached = true
+    end
+    private_class_method :attach_api
+
+    def ensure_generated_api!
+      return if defined?(Qt::BridgeAPI::FUNCTIONS)
+
+      root = File.expand_path('../..', __dir__)
+      generated_api = File.join(root, 'build', 'generated', 'bridge_api.rb')
+      generator = File.join(root, 'scripts', 'generate_bridge.rb')
+      system(RbConfig.ruby, generator) unless File.exist?(generated_api)
+      require generated_api
+    end
+    private_class_method :ensure_generated_api!
+  end
+end

data/lib/qt/children_tracking.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Qt
+  # Child object tracking to mirror Qt parent/child ownership in Ruby.
+  module ChildrenTracking
+    def init_children_tracking!
+      @children = []
+    end
+
+    def add_child(child)
+      @children ||= []
+      @children << child
+    end
+  end
+end

data/lib/qt/constants.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'generated_constants_runtime'
+
+module Qt
+  GENERATED_CONSTANTS = File.expand_path('../../build/generated/constants.rb', __dir__)
+  require GENERATED_CONSTANTS if File.exist?(GENERATED_CONSTANTS)
+
+  GeneratedConstantsRuntime.apply_key_aliases!(self)
+end

data/lib/qt/date_time_codec.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'time'
+
+module Qt
+  # Codec for typed QDateTime/QDate/QTime bridge payloads.
+  module DateTimeCodec
+    module_function
+
+    DATETIME_PREFIX = 'qtdt:'
+    DATE_PREFIX = 'qtdate:'
+    TIME_PREFIX = 'qttime:'
+
+    def encode_qdatetime(value)
+      time = coerce_to_time(value)
+      "#{DATETIME_PREFIX}#{time.iso8601(6)}"
+    end
+
+    def decode_qdatetime(value)
+      raw = StringCodec.from_qt_text(value.to_s)
+      payload = raw.start_with?(DATETIME_PREFIX) ? raw.delete_prefix(DATETIME_PREFIX) : raw
+      Time.iso8601(payload)
+    rescue ArgumentError
+      Time.at(0).utc
+    end
+
+    def encode_qdate(value)
+      date = coerce_to_date(value)
+      "#{DATE_PREFIX}#{date.strftime('%Y-%m-%d')}"
+    end
+
+    def decode_qdate(value)
+      raw = StringCodec.from_qt_text(value.to_s)
+      payload = raw.start_with?(DATE_PREFIX) ? raw.delete_prefix(DATE_PREFIX) : raw
+      Date.iso8601(payload)
+    rescue ArgumentError
+      Date.new(1970, 1, 1)
+    end
+
+    def encode_qtime(value)
+      time_string =
+        case value
+        when Time then value.strftime('%H:%M:%S')
+        else normalize_time_string(value.to_s)
+        end
+      "#{TIME_PREFIX}#{time_string}"
+    end
+
+    def decode_qtime(value)
+      raw = StringCodec.from_qt_text(value.to_s)
+      payload = raw.start_with?(TIME_PREFIX) ? raw.delete_prefix(TIME_PREFIX) : raw
+      normalize_time_string(payload)
+    rescue ArgumentError
+      '00:00:00'
+    end
+
+    def decode_for_signal(signal_name, payload)
+      return nil if payload.nil?
+
+      signature = signal_name.to_s
+      if signature.start_with?('dateTimeChanged(')
+        return decode_qdatetime(payload)
+      end
+      if signature.start_with?('dateChanged(')
+        return decode_qdate(payload)
+      end
+      if signature.start_with?('timeChanged(')
+        return decode_qtime(payload)
+      end
+
+      StringCodec.from_qt_text(payload)
+    end
+
+    def coerce_to_time(value)
+      return value if value.is_a?(Time)
+      return value.to_time if value.respond_to?(:to_time)
+
+      Time.iso8601(value.to_s)
+    rescue ArgumentError
+      Time.at(0).utc
+    end
+
+    def coerce_to_date(value)
+      return value if value.is_a?(Date)
+      return value.to_date if value.respond_to?(:to_date)
+
+      Date.iso8601(value.to_s)
+    rescue ArgumentError
+      Date.new(1970, 1, 1)
+    end
+
+    def normalize_time_string(value)
+      raw = value.to_s.strip
+      raise ArgumentError, 'time is empty' if raw.empty?
+
+      return "#{raw}:00" if raw.match?(/\A\d{2}:\d{2}\z/)
+      return raw if raw.match?(/\A\d{2}:\d{2}:\d{2}\z/)
+
+      parsed = Time.parse(raw)
+      parsed.strftime('%H:%M:%S')
+    end
+  end
+end

data/lib/qt/errors.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Qt
+  class Error < StandardError; end
+  class NativeExtensionError < Error; end
+end

data/lib/qt/event_runtime.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Qt
+  # Event/signal subscription runtime backed by generated native callbacks.
+  module EventRuntime
+    module_function
+
+    def on_event(widget, event_name, &block)
+      raise ArgumentError, 'pass block to on_event' unless block
+
+      ensure_native_bridge_ready!
+      ensure_event_callback!
+
+      event_type = event_type_for(event_name)
+      handle = widget_handle(widget) || raise(ArgumentError, 'widget handle is required')
+
+      @event_handlers ||= {}
+      ((@event_handlers[handle.address] ||= {})[event_type] ||= []) << block
+
+      Qt::Native.watch_qobject_event(handle, event_type)
+      true
+    end
+
+    def on_signal(widget, signal_name, &block)
+      raise ArgumentError, 'pass block to on_signal' unless block
+
+      ensure_native_bridge_ready!
+      ensure_signal_callback!
+
+      handle = widget_handle(widget) || raise(ArgumentError, 'widget handle is required')
+      per_signal = prepare_signal_registration(handle, signal_name)
+      per_signal[:blocks] << block
+      true
+    end
+
+    def prepare_signal_registration(handle, signal_name)
+      signal_key = signal_name.to_s
+      raise ArgumentError, 'signal name is required' if signal_key.empty?
+
+      @signal_handlers ||= {}
+      per_signal = ((@signal_handlers[handle.address] ||= {})[signal_key] ||= { index: nil, blocks: [] })
+      if per_signal[:index].nil?
+        index = Qt::Native.qobject_connect_signal(handle, signal_key)
+        raise ArgumentError, "failed to connect signal #{signal_key.inspect} (code=#{index})" if index.negative?
+
+        per_signal[:index] = index
+      end
+      per_signal
+    end
+
+    def off_signal(widget, signal_name = nil)
+      ensure_native_bridge_ready!
+      handle = widget_handle(widget)
+      return false if handle.nil? || @signal_handlers.nil?
+
+      per_widget = @signal_handlers[handle.address]
+      return false if per_widget.nil?
+
+      signal_key = signal_name&.to_s
+      per_widget.delete(signal_key) if signal_key
+      per_widget.clear unless signal_key
+      Qt::Native.qobject_disconnect_signal(handle, signal_key)
+      true
+    end
+
+    def off_event(widget, event_name = nil)
+      ensure_native_bridge_ready!
+      handle = widget_handle(widget)
+      return false if handle.nil? || @event_handlers.nil?
+
+      per_widget = @event_handlers[handle.address]
+      return false unless per_widget
+
+      off_event_for_widget(handle, per_widget, event_name)
+      true
+    end
+
+    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]
+      raise ArgumentError, "unknown event: #{event_name.inspect}" unless event_type
+
+      event_type
+    end
+
+    def ensure_event_callback!
+      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 }
+        EventRuntimeDispatch.dispatch_event(@event_handlers, object_handle, event_type, payload)
+      end
+
+      Qt::Native.set_event_callback(@event_callback)
+    end
+
+    def ensure_signal_callback!
+      return if @signal_callback
+
+      @signal_callback = FFI::Function.new(:void, %i[pointer int string]) do |object_handle, signal_index, payload|
+        normalized_payload = payload.nil? ? nil : Qt::StringCodec.from_qt_text(payload)
+        EventRuntimeDispatch.dispatch_signal(@signal_handlers, object_handle, signal_index, normalized_payload)
+      end
+
+      Qt::Native.set_signal_callback(@signal_callback)
+    end
+
+    def widget_handle(widget)
+      return nil if widget.nil?
+
+      widget.respond_to?(:handle) ? widget.handle : widget
+    end
+
+    def ensure_native_bridge_ready!
+      Qt::Native.ensure_loaded!
+      Qt::Native.define_bridge_wrappers!
+    end
+
+    def off_event_for_widget(handle, per_widget, event_name)
+      if event_name
+        event_type = event_type_for(event_name)
+        per_widget.delete(event_type)
+        Qt::Native.unwatch_qobject_event(handle, event_type)
+      else
+        per_widget.each_key { |event_type| Qt::Native.unwatch_qobject_event(handle, event_type) }
+        @event_handlers.delete(handle.address)
+      end
+    end
+  end
+end

data/lib/qt/event_runtime_dispatch.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Dispatch helpers for event/signal callbacks from the native bridge.
+module Qt
+  # Dispatch helpers for event/signal callbacks from the native bridge.
+  module EventRuntimeDispatch
+    module_function
+
+    def dispatch_event(event_handlers, object_handle, event_type, payload)
+      return unless object_handle && event_handlers
+
+      per_widget = event_handlers[object_handle.address]
+      return unless per_widget
+
+      handlers = per_widget[event_type]
+      return unless handlers && !handlers.empty?
+
+      handlers.each { |handler| handler.call(payload) }
+    end
+
+    def dispatch_signal(signal_handlers, object_handle, signal_index, payload)
+      return unless object_handle && signal_handlers
+
+      per_widget = signal_handlers[object_handle.address]
+      return unless per_widget
+
+      per_widget.each do |signal_name, entry|
+        next unless entry[:index] == signal_index
+
+        typed_payload = Qt::DateTimeCodec.decode_for_signal(signal_name, payload)
+        entry[:blocks].each { |handler| handler.call(typed_payload) }
+      end
+    end
+  end
+end

data/lib/qt/event_runtime_qobject_methods.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# QObject-level event/signal helper methods mixed into generated classes.
+module Qt
+  module EventRuntime
+    # QObject-level event/signal helper methods mixed into generated classes.
+    module QObjectMethods
+      def on(event_name, &block)
+        raise ArgumentError, 'pass block to on' unless block
+
+        EventRuntime.on_event(self, event_name, &block)
+        self
+      end
+      alias on_event on
+
+      def connect(signal_name, &block)
+        raise ArgumentError, 'pass block to connect' unless block
+
+        EventRuntime.on_signal(self, signal_name, &block)
+        self
+      end
+      alias on_signal connect
+      alias slot connect
+
+      def off(event_name = nil)
+        EventRuntime.off_event(self, event_name)
+        self
+      end
+      alias off_event off
+
+      def disconnect(signal_name = nil)
+        EventRuntime.off_signal(self, signal_name)
+        self
+      end
+      alias off_signal disconnect
+    end
+
+    # Backward-compatible alias for already-generated code.
+    WidgetMethods = QObjectMethods
+  end
+end

data/lib/qt/generated_constants_runtime.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Qt
+  module GeneratedConstantsRuntime
+    module_function
+
+    def apply_generated_scoped_constants!(qt_module)
+      return unless qt_module.const_defined?(:GENERATED_SCOPED_CONSTANTS, false)
+
+      qt_module.const_get(:GENERATED_SCOPED_CONSTANTS, false).each do |owner_name, owner_constants|
+        next unless qt_module.const_defined?(owner_name, false)
+
+        owner = qt_module.const_get(owner_name, false)
+        owner_constants.each do |const_name, const_value|
+          next if owner.const_defined?(const_name, false)
+
+          owner.const_set(const_name, const_value)
+        end
+      end
+    end
+
+    def apply_key_aliases!(qt_module)
+      qt_module.constants(false).grep(/\AKey_[A-Za-z0-9_]+\z/).each do |source_name|
+        suffix = source_name.to_s.sub(/\AKey_/, '')
+        alias_name = "Key#{suffix.split('_').map(&:capitalize).join}"
+        next unless alias_name.match?(/\A[A-Z][A-Za-z0-9_]*\z/)
+        next if qt_module.const_defined?(alias_name, false)
+
+        qt_module.const_set(alias_name, qt_module.const_get(source_name, false))
+      end
+    end
+  end
+end

data/lib/qt/inspectable.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Qt
+  # Common object inspection formatting for Qt wrapper instances.
+  module Inspectable
+    def q_inspect_property_values
+      property_values = {}
+      self.class::QT_API_PROPERTIES.each do |property|
+        property_values[property] = public_send(property)
+      rescue StandardError => e
+        property_values[property] = { error: e.class.name, message: e.message }
+      end
+      property_values
+    end
+
+    def q_inspect
+      {
+        qt_class: self.class::QT_CLASS,
+        ruby_class: self.class.name,
+        handle: @handle,
+        qt_methods: self.class::QT_API_QT_METHODS,
+        ruby_methods: self.class::QT_API_RUBY_METHODS,
+        properties: q_inspect_property_values
+      }
+    end
+    alias qt_inspect q_inspect
+    alias to_h q_inspect
+  end
+end

data/lib/qt/key_sequence_codec.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Qt
+  # Conversion helpers for QKeySequence bridge arguments.
+  module KeySequenceCodec
+    module_function
+
+    def encode(value)
+      return '' if value.nil?
+      return Qt::StringCodec.to_qt_text(value) if value.is_a?(String)
+
+      if value.respond_to?(:to_string)
+        return Qt::StringCodec.to_qt_text(value.to_string)
+      end
+      if value.respond_to?(:toString)
+        return Qt::StringCodec.to_qt_text(value.toString)
+      end
+
+      Qt::StringCodec.to_qt_text(value.to_s)
+    end
+  end
+end

data/lib/qt/native.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Qt
+  # Thin FFI access layer for generated bridge entry points.
+  module Native
+    require 'ffi'
+
+    ROOT = File.expand_path('../..', __dir__)
+    GENERATED_API = File.join(ROOT, 'build', 'generated', 'bridge_api.rb')
+
+    require GENERATED_API if File.exist?(GENERATED_API)
+
+    COERCERS = {
+      string: :to_s.to_proc,
+      int: ->(value) { Integer(value) },
+      bool: ->(value) { !value.nil? && value != false },
+      pointer: lambda { |value|
+        return nil if value.nil?
+
+        value.respond_to?(:handle) ? value.handle : value
+      }
+    }.freeze
+
+    module_function
+
+    def available?
+      return @available unless @available.nil?
+
+      @available = Bridge.load! && Bridge.loaded?
+    end
+
+    def ensure_loaded!
+      return if available?
+
+      detail = Bridge.load_error ? " (#{Bridge.load_error.message})" : ''
+      raise NativeExtensionError,
+            "Qt bridge is not available. Build it with: bundle exec rake compile#{detail}"
+    end
+
+    def define_bridge_wrappers!
+      return if @bridge_wrappers_defined
+      return unless defined?(Qt::BridgeAPI::FUNCTIONS)
+
+      Qt::BridgeAPI::FUNCTIONS.each do |fn|
+        define_bridge_wrapper(fn)
+      end
+
+      @bridge_wrappers_defined = true
+    end
+
+    def define_bridge_wrapper(function_spec)
+      native_name = function_spec[:name].to_s.sub(/\Aqt_ruby_/, '')
+      signature = function_spec[:args]
+      bridge_name = function_spec[:name]
+
+      define_singleton_method(native_name) do |*args|
+        ensure_loaded!
+        normalized = normalize_bridge_args(args, signature)
+        converted = coerce_bridge_args(normalized, signature)
+        Bridge.public_send(bridge_name, *converted)
+      end
+    end
+
+    def normalize_bridge_args(args, signature)
+      if args.length < signature.length
+        ensure_missing_args_optional!(args, signature)
+
+        return args + ([nil] * (signature.length - args.length))
+      end
+      raise_wrong_arity(args.length, signature.length) if args.length > signature.length
+
+      args
+    end
+
+    def ensure_missing_args_optional!(args, signature)
+      missing = signature[args.length..]
+      raise_wrong_arity(args.length, signature.length) unless missing.all? { |type| type == :pointer }
+    end
+
+    def raise_wrong_arity(given, expected)
+      raise ArgumentError, "wrong number of arguments (given #{given}, expected #{expected})"
+    end
+
+    def coerce_bridge_args(args, signature)
+      args.zip(signature).map do |value, type|
+        coercer = COERCERS[type]
+        coercer ? coercer.call(value) : value
+      end
+    end
+
+    define_bridge_wrappers!
+  end
+end

data/lib/qt/shortcut_compat.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Qt
+  # Backward-compatible QShortcut#set_keys handling for QKeySequence inputs.
+  module ShortcutCompat
+    module_function
+
+    def key_sequence_like?(value)
+      value.is_a?(String) || value.respond_to?(:to_string) || value.respond_to?(:toString)
+    end
+  end
+end
+
+if defined?(Qt::QShortcut)
+  module Qt
+    class QShortcut
+      if instance_methods(false).include?(:set_keys) && !instance_methods(false).include?(:set_keys_without_qkeysequence_compat)
+        alias_method :set_keys_without_qkeysequence_compat, :set_keys
+      end
+
+      def set_keys(value)
+        if respond_to?(:set_key) && ShortcutCompat.key_sequence_like?(value)
+          set_key(value)
+        else
+          set_keys_without_qkeysequence_compat(value)
+        end
+      end
+    end
+  end
+end