rbnput-darwin-minimal 0.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3317cf0ccce42301ac2051688baf804f1f17f56bdf71b2af9c6a8e27b90d4869
-  data.tar.gz: c11a98352c3eff90c3618188ee865501649b48a6fb1fa23342871e9e2fe35e0e
+  metadata.gz: bde651d183da7dc9b3e17dcf9a4789fb1f2e16ca089909f8440b87056a23baf7
+  data.tar.gz: eb0416ba45e6545674ff3cbf12172db87feee358fddd3eeedfa96056869e6f6a
 SHA512:
-  metadata.gz: 5a019ea1d2117c1794eacfd1a4583b319bde5cd0ee030d6c208c66fa6ae7a8d7c1c8e9b8904108e6590562672f3e4e0da3893e34011750d39e20b3b2baabc9aa
-  data.tar.gz: 887fe4b1c904f54da8b42d0a28556c5933c06a839cf79665e33a3d4050f6bb4b94bbca18ed3dbc78ba8bf978d39697e3b39564cf1e489a7c26449a7cdc2aaef4
+  metadata.gz: 9ae0c01ddfcc21e87a38e3d5977ff54a7233ff73bbf9544bb1903534ca6cc26388abbc9c2871a34e00b271aec767f58e00d3191445e5abb6f3b984d0a55c92f0
+  data.tar.gz: 3f8b61f1abdeae98b6ba07ce6f1126ea6142df78fe446d8a5933dab1b57384bb23e5ca68adcb2d9b654307a851ba67b4ded64b2eb105f7612ebc6e3643b0eb09

data/README.md

@@ -1,5 +1,8 @@
 # 🎹 rbnput-darwin-minimal 🍎
 
+[![Gem Version](https://badge.fury.io/rb/rbnput-darwin-minimal.svg)](https://badge.fury.io/rb/rbnput-darwin-minimal)
+[![GitHub](https://img.shields.io/badge/github-repo-blue)](https://github.com/krist7599555/rbnput-darwin-minimal)
+
 ไลบรารี Ruby ขนาดเล็กสำหรับตรวจจับการกดแป้นพิมพ์บนระบบ macOS โดยใช้ FFI เชื่อมต่อกับ system library ของ Darwin โดยตรง
 
 ## ✨ คุณสมบัติ

data/lib/rbnput/darwin_ffi.rb

@@ -2,67 +2,151 @@
 
 require 'ffi'
 
-module Rbnput::DarwinFFI
-  extend FFI::Library
-  ffi_lib ['/System/Library/Frameworks/ApplicationServices.framework/ApplicationServices',
-            '/System/Library/Frameworks/CoreFoundation.framework/CoreFoundation']
-
-  # CoreFoundation types
-  typedef :pointer, :CFMachPortRef
-  typedef :pointer, :CFRunLoopSourceRef
-  typedef :pointer, :CFRunLoopRef
-  typedef :pointer, :CFStringRef
-  typedef :pointer, :CGEventTapProxy
-  typedef :pointer, :CGEventRef
-  
-  # Constants
-  KCGSessionEventTap = 0
-  KCGHeadInsertEventTap = 0
-  KCGEventTapOptionDefault = 0x00000000
-  KCGEventTapOptionListenOnly = 0x00000001
-  
-  KCFRunLoopRunFinished = 1
-  KCFRunLoopRunStopped = 2
-  KCFRunLoopRunTimedOut = 3
-  KCFRunLoopRunHandledSource = 4
-
-  KCGEventSourceUnixProcessID = 1
-  KCGKeyboardEventKeycode = 9
-
-  KCGScrollWheelEventDeltaAxis1 = 11 # Y
-  KCGScrollWheelEventDeltaAxis2 = 12 # X 
-
-  KCGEventKeyDown = 10
-  KCGEventKeyUp = 11
-  KCGEventFlagsChanged = 12
-  
-  # We need to get the kCFRunLoopDefaultMode constant value
-  # It's a CFStringRef. For simplicity in FFI, we can often pass NULL (0) for default mode in some APIs,
-  # but CFRunLoopAddSource requires a mode.
-  # A common workaround is to look it up or define it if we know the symbol name.
-  # However, getting the actual pointer value of a constant exported by a dylib in FFI can be tricky.
-  # We'll try to attach it.
-  attach_variable :kCFRunLoopDefaultMode, :kCFRunLoopDefaultMode, :pointer
-
-  # CGEventTapCallback
-  callback :CGEventTapCallback, [:pointer, :int, :pointer, :pointer], :pointer
-
-  # Functions
-  attach_function :CGEventTapCreate, [:int, :int, :int, :uint64, :CGEventTapCallback, :pointer], :CFMachPortRef
-  attach_function :CGEventTapEnable, [:CFMachPortRef, :bool], :void
-  attach_function :CFMachPortCreateRunLoopSource, [:pointer, :CFMachPortRef, :long], :CFRunLoopSourceRef
-  attach_function :CFRunLoopGetCurrent, [], :CFRunLoopRef
-  attach_function :CFRunLoopAddSource, [:CFRunLoopRef, :CFRunLoopSourceRef, :pointer], :void
-  attach_function :CFRunLoopRunInMode, [:pointer, :double, :bool], :int
-  attach_function :CFRunLoopStop, [:CFRunLoopRef], :void
-  attach_function :CFRelease, [:pointer], :void
-  attach_function :AXIsProcessTrusted, [], :bool
-  attach_function :CGEventGetIntegerValueField, [:pointer, :int], :int64
-  attach_function :CGEventGetType, [:pointer], :int
-  attach_function :CGEventGetFlags, [:pointer], :uint64
-  attach_function :CGEventCreateKeyboardEvent, [:pointer, :uint16, :bool], :pointer
-  attach_function :CGEventPost, [:int, :pointer], :void
-  attach_function :CGEventSourceCreate, [:int], :pointer
-  attach_function :CFRelease, [:pointer], :void
-  attach_function :CGEventSetFlags, [:pointer, :uint64], :void
+module Rbnput
+  # FFI bindings for macOS ApplicationServices and CoreFoundation.
+  # Provides low-level access to Quartz Event Services.
+  #
+  # @api private
+  module DarwinFFI
+    extend FFI::Library
+    ffi_lib ['/System/Library/Frameworks/ApplicationServices.framework/ApplicationServices',
+              '/System/Library/Frameworks/CoreFoundation.framework/CoreFoundation']
+
+    # CoreFoundation types
+    typedef :pointer, :CFMachPortRef
+    typedef :pointer, :CFRunLoopSourceRef
+    typedef :pointer, :CFRunLoopRef
+    typedef :pointer, :CFStringRef
+    typedef :pointer, :CGEventTapProxy
+    typedef :pointer, :CGEventRef
+    
+    # Constants
+    KCGSessionEventTap = 0
+    KCGHeadInsertEventTap = 0
+    KCGEventTapOptionDefault = 0x00000000
+    KCGEventTapOptionListenOnly = 0x00000001
+    
+    KCFRunLoopRunFinished = 1
+    KCFRunLoopRunStopped = 2
+    KCFRunLoopRunTimedOut = 3
+    KCFRunLoopRunHandledSource = 4
+
+    KCGEventSourceUnixProcessID = 1
+    KCGKeyboardEventKeycode = 9
+
+    KCGScrollWheelEventDeltaAxis1 = 11 # Y
+    KCGScrollWheelEventDeltaAxis2 = 12 # X 
+
+    KCGEventKeyDown = 10
+    KCGEventKeyUp = 11
+    KCGEventFlagsChanged = 12
+    
+    # We need to get the kCFRunLoopDefaultMode constant value
+    # It's a CFStringRef. For simplicity in FFI, we can often pass NULL (0) for default mode in some APIs,
+    # but CFRunLoopAddSource requires a mode.
+    # A common workaround is to look it up or define it if we know the symbol name.
+    # However, getting the actual pointer value of a constant exported by a dylib in FFI can be tricky.
+    # We'll try to attach it.
+    attach_variable :kCFRunLoopDefaultMode, :kCFRunLoopDefaultMode, :pointer
+
+    # CGEventTapCallback function signature
+    # @param proxy [CGEventTapProxy]
+    # @param type [Integer] The event type
+    # @param event [CGEventRef] The event reference
+    # @param refcon [Pointer] User data
+    # @return [CGEventRef] The event to pass through, or NULL to suppress
+    callback :CGEventTapCallback, [:pointer, :int, :pointer, :pointer], :pointer
+
+    # Functions
+
+    # Creates an event tap.
+    # @param tapLocation [Integer]
+    # @param place [Integer]
+    # @param options [Integer]
+    # @param eventsOfInterest [Integer] Mask of events to listen for
+    # @param callback [Proc] Block to be called
+    # @param userInfo [Pointer]
+    # @return [CFMachPortRef]
+    attach_function :CGEventTapCreate, [:int, :int, :int, :uint64, :CGEventTapCallback, :pointer], :CFMachPortRef
+
+    # Enables or disables an event tap.
+    # @param tap [CFMachPortRef]
+    # @param enable [Boolean]
+    attach_function :CGEventTapEnable, [:CFMachPortRef, :bool], :void
+
+    # Creates a run loop source for a Mach port.
+    # @param allocator [Pointer]
+    # @param port [CFMachPortRef]
+    # @param order [Integer]
+    # @return [CFRunLoopSourceRef]
+    attach_function :CFMachPortCreateRunLoopSource, [:pointer, :CFMachPortRef, :long], :CFRunLoopSourceRef
+
+    # Returns the current run loop.
+    # @return [CFRunLoopRef]
+    attach_function :CFRunLoopGetCurrent, [], :CFRunLoopRef
+
+    # Adds a source to a run loop mode.
+    # @param rl [CFRunLoopRef]
+    # @param source [CFRunLoopSourceRef]
+    # @param mode [CFStringRef]
+    attach_function :CFRunLoopAddSource, [:CFRunLoopRef, :CFRunLoopSourceRef, :pointer], :void
+
+    # Runs the current run loop in a specific mode.
+    # @param mode [CFStringRef]
+    # @param seconds [Float]
+    # @param returnAfterSourceHandled [Boolean]
+    # @return [Integer] Result code
+    attach_function :CFRunLoopRunInMode, [:pointer, :double, :bool], :int
+
+    # Stops a run loop.
+    # @param rl [CFRunLoopRef]
+    attach_function :CFRunLoopStop, [:CFRunLoopRef], :void
+
+    # RE-DEFINED: Removes a value from a retain/release system.
+    # This was defined twice in the original file, keeping one.
+    # @param cf [Pointer]
+    attach_function :CFRelease, [:pointer], :void
+
+    # Checks if the current process is trusted for accessibility.
+    # @return [Boolean]
+    attach_function :AXIsProcessTrusted, [], :bool
+
+    # Gets an integer value from an event field.
+    # @param event [CGEventRef]
+    # @param field [Integer]
+    # @return [Integer]
+    attach_function :CGEventGetIntegerValueField, [:pointer, :int], :int64
+
+    # Gets the event type.
+    # @param event [CGEventRef]
+    # @return [Integer]
+    attach_function :CGEventGetType, [:pointer], :int
+
+    # Gets the event flags.
+    # @param event [CGEventRef]
+    # @return [Integer]
+    attach_function :CGEventGetFlags, [:pointer], :uint64
+
+    # Creates a keyboard event.
+    # @param source [Pointer]
+    # @param virtualKey [Integer]
+    # @param keyDown [Boolean]
+    # @return [CGEventRef]
+    attach_function :CGEventCreateKeyboardEvent, [:pointer, :uint16, :bool], :pointer
+
+    # Posts an event to the event stream.
+    # @param tapLocation [Integer]
+    # @param event [CGEventRef]
+    attach_function :CGEventPost, [:int, :pointer], :void
+
+    # Creates an event source.
+    # @param stateID [Integer]
+    # @return [Pointer]
+    attach_function :CGEventSourceCreate, [:int], :pointer
+
+    # Sets the event flags.
+    # @param event [CGEventRef]
+    # @param flags [Integer]
+    attach_function :CGEventSetFlags, [:pointer, :uint64], :void
+  end
 end

data/lib/rbnput/darwin_listener.rb

@@ -7,83 +7,122 @@ require_relative './darwin_ffi'
 
 module Rbnput
   # Base listener for keyboard events
+  # คลาส Listener พื้นฐานสำหรับเหตุการณ์คีย์บอร์ด บน macOS
   class DarwinListener < Rbnput::SimpleMutexThread
+    # Initializes the DarwinListener.
+    # สร้าง instance ใหม่สำหรับดักจับคีย์บอร์ด
+    #
+    # @param on_press [Proc, nil] Callback when a key is pressed.
+    # @param on_release [Proc, nil] Callback when a key is released.
+    # @param kwargs [Hash] Additional options passed to SimpleMutexThread.
     def initialize(on_press: nil, on_release: nil, **kwargs)
       super(*kwargs)
-      @on_press = on_press
-      @on_release = on_release
+      @on_press = on_press     # callback เมื่อกดปุ่ม
+      @on_release = on_release # callback เมื่อปล่อยปุ่ม
 
       @loop = nil
       @tap = nil
-      @callback_proc = nil # Keep reference to prevent GC
+      @callback_proc = nil # Keep reference to prevent GC (เก็บ reference ไว้เพื่อป้องกัน Garbage Collection)
     end
     attr_reader :on_press, :on_release
 
+    # Sets the callback for key press events.
+    # ตั้งค่า callback สำหรับการกดปุ่ม
+    #
+    # @yield [key]
+    # @yieldparam key [KeyCode] The key that was pressed.
     def on_press(&proc)
       @on_press = proc
     end
+    
+    # Sets the callback for key release events.
+    # ตั้งค่า callback สำหรับการปล่อยปุ่ม
+    #
+    # @yield [key]
+    # @yieldparam key [KeyCode] The key that was released.
     def on_release(&proc)
-      @on_press = proc
+      @on_release = proc
     end
 
+    # The main run loop for the listener.
+    # Internal method called by the thread.
+    #
+    # @api private
     def _run
+      # ตรวจสอบว่า Process ได้รับสิทธิ์ Accessibility หรือไม่
       unless Rbnput::DarwinFFI.AXIsProcessTrusted()
         @log.warn("Process is not trusted! Input monitoring will not work until added to accessibility clients.")
+        @log.warn("โปรแกรมนี้ยังไม่ได้รับสิทธิ์ Accessibility! การดักจับอินพุตจะไม่ทำงานจนกว่าจะได้รับอนุญาต")
       end
 
       # Create the callback
+      # สร้าง callback function ที่จะถูกเรียกเมื่อมี event
       @callback_proc = FFI::Function.new(:pointer, [:pointer, :int, :pointer, :pointer]) do |proxy, type, event, refcon|
+        # ดึงค่า key code จาก event และแปลงเป็น KeyCode object
         key_code = DarwinFFI
           .CGEventGetIntegerValueField(event, Rbnput::DarwinFFI::KCGKeyboardEventKeycode)
           .then { |vk| KeyCode.from_vk(vk) }
         
         case type
-        when Rbnput::DarwinFFI::KCGEventKeyDown;      @on_press&.call(key_code)
-        when Rbnput::DarwinFFI::KCGEventKeyUp;        @on_release&.call(key_code)
-        when Rbnput::DarwinFFI::KCGEventFlagsChanged; @on_press&.call(key_code)
+        when Rbnput::DarwinFFI::KCGEventKeyDown;      @on_press&.call(key_code)   # กดปุ่ม
+        when Rbnput::DarwinFFI::KCGEventKeyUp;        @on_release&.call(key_code) # ปล่อยปุ่ม
+        when Rbnput::DarwinFFI::KCGEventFlagsChanged; @on_press&.call(key_code)   # ปุ่ม Modifier เปลี่ยนแปลง (เช่น Shift, Ctrl)
         end
         event
       end
 
+      # สร้าง Event Tap เพื่อดักจับ event ของระบบ
       @tap = Rbnput::DarwinFFI.CGEventTapCreate(
         Rbnput::DarwinFFI::KCGSessionEventTap,
         Rbnput::DarwinFFI::KCGHeadInsertEventTap,
         Rbnput::DarwinFFI::KCGEventTapOptionDefault,
-        (1 << Rbnput::DarwinFFI::KCGEventKeyDown)  | (1 << Rbnput::DarwinFFI::KCGEventKeyUp) | (1 << Rbnput::DarwinFFI::KCGEventFlagsChanged),
+        (1 << Rbnput::DarwinFFI::KCGEventKeyDown)  | (1 << Rbnput::DarwinFFI::KCGEventKeyUp) | (1 << Rbnput::DarwinFFI::KCGEventFlagsChanged), # ระบุประเภท event ที่ต้องการดักจับ
         @callback_proc,
         nil
       )
 
       if @tap.null?
         @log.error("Failed to create event tap")
+        @log.error("ไม่สามารถสร้าง event tap ได้")
         return
       end
 
       # Create run loop source
+      # สร้าง run loop source จาก tap
       source = Rbnput::DarwinFFI.CFMachPortCreateRunLoopSource(nil, @tap, 0)
       
       # Add to current run loop
+      # เพิ่ม source เข้าไปใน run loop ปัจจุบัน
       @loop = Rbnput::DarwinFFI.CFRunLoopGetCurrent()
       Rbnput::DarwinFFI.CFRunLoopAddSource(@loop, source, Rbnput::DarwinFFI.kCFRunLoopDefaultMode)
       
       # Enable tap
+      # เปิดใช้งาน tap
       Rbnput::DarwinFFI.CGEventTapEnable(@tap, true)
       
       # Run loop
+      # เริ่มทำงาน loop เพื่อรอรับ event
       while @running
         _result = Rbnput::DarwinFFI.CFRunLoopRunInMode(Rbnput::DarwinFFI.kCFRunLoopDefaultMode, 0.1, false)
         
         # 0.1 second timeout allows us to check @running flag
+        # timeout 0.1 วินาที เพื่อให้สามารถตรวจสอบ flag @running ได้ (เพื่อให้หยุด loop ได้อย่างนุ่มนวล)
       end
     ensure
+      # Cleanup เมื่อจบการทำงาน
       Rbnput::DarwinFFI.CFRelease(@tap) if @tap && !@tap.null?
       Rbnput::DarwinFFI.CFRelease(source) if source && !source.null?
       @tap = nil
       @loop = nil
     end
 
+    # Stops the listener and the run loop.
+    # หยุดการทำงานของ listener
+    #
+    # @return [void]
     def stop
       super
+      # หยุด run loop
       Rbnput::DarwinFFI.CFRunLoopStop(@loop) if @loop && !@loop.null?
     end
 

data/lib/rbnput/key_code.rb

@@ -3,11 +3,15 @@ require_relative "./key_code_const"
 class Rbnput::KeyCode
   attr_reader :vk, :is_media
 
+  # สร้าง Object KeyCode
+  # @param vk [Integer] Virtual Key Code
+  # @param is_media [Boolean] เป็น Media Key หรือไม่
   def initialize(vk: nil, is_media: false)
     @vk = vk
     @is_media = is_media
   end
 
+  # แปลงเป็น String สำหรับแสดงผล
   def to_s
     [
       @vk.nil? ? "" : "vk=#{@vk}",
@@ -18,10 +22,12 @@ class Rbnput::KeyCode
     .then { "KeyCode(#{_1}, #{key})" }
   end
 
+  # ชื่อของปุ่ม (จากค่า vk)
   def key
     KEY_CODE_HEX_TO_NAME[@vk] || "UNKNOW"
   end
 
+  # เปรียบเทียบ object
   def ==(other)
     return false unless other.is_a?(KeyCode)
     @vk == other.vk && @is_media == other.is_media
@@ -33,10 +39,12 @@ class Rbnput::KeyCode
     [@vk, @is_media].hash
   end
 
+  # สร้าง KeyCode จาก Virtual Key
   def self.from_vk(vk, **kwargs)
     new(vk: vk, is_media: false, **kwargs)
   end
 
+  # สร้าง KeyCode จาก Media Key
   def self.from_media(vk, **kwargs)
     new(vk: vk, is_media: true, **kwargs)
   end

data/lib/rbnput/key_code_const.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+# Mapping from key names to macOS unique virtual key codes (Hex).
+# Based on the system header files.
 KEY_CODE_NAME_TO_HEX = {
   :kVK_ANSI_A => 0x00,
   :kVK_ANSI_S => 0x01,
@@ -125,4 +129,5 @@ KEY_CODE_NAME_TO_HEX = {
   # NX_KEYTYPE_REWIND = 20
 }
 
+# Reverse mapping from virtual key codes to key names.
 KEY_CODE_HEX_TO_NAME = KEY_CODE_NAME_TO_HEX.invert

data/lib/rbnput/simple_mutex_thread.rb

@@ -2,22 +2,35 @@
 
 require 'thread'
 
+# A simple thread wrapper with mutex synchronization.
+# Provides a base class for threaded listeners.
 class Rbnput::SimpleMutexThread
 
   protected
-  # Platform-specific run implementation
-  # Must be implemented by subclasses
+  
+  # Platform-specific run implementation.
+  # Must be implemented by subclasses.
+  #
+  # @return [void]
+  # @raise [NotImplementedError] If not implemented by subclass
   def _run; raise NotImplementedError, "Subclasses must implement _run" end
 
   public
+  
+  # @return [Boolean] true if the thread is running
   attr_reader :running
+  
+  # Initializes the SimpleMutexThread.
   def initialize
     @running = false
     @thread = nil
     @mutex = Mutex.new
   end
 
-  # Start the listener in a separate thread
+  # Starts the listener in a separate thread.
+  # Check is running before start new thread.
+  #
+  # @return [self]
   def start
     @mutex.synchronize do
       return if @running
@@ -30,14 +43,24 @@ class Rbnput::SimpleMutexThread
     self
   end
 
-  # Stop the listener
+  # Stops the listener.
+  # Sets running flag to false and waits for the thread to exit.
+  #
+  # @return [self]
   def stop
     @mutex.synchronize do; @running = false end
     @thread&.join(5) # Wait up to 5 seconds
     self
   end
 
+  # Joins the thread.
+  #
+  # @return [Thread, nil]
   def join; @thread&.join end
+  
+  # Checks if the thread is alive.
+  #
+  # @return [Boolean]
   def alive?; @running && @thread&.alive? end
 
 

data/lib/rbnput/version.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module Rbnput
-  VERSION = "0.2.0"
+  # Current version of the gem
+  VERSION = "1.4.0"
+  
+  # Gem Author
   AUTHOR = "Krist Ponpairin"
 end

data/lib/rbnput-darwin-minimal.rb

@@ -18,9 +18,12 @@ require_relative "rbnput/darwin_listener"
 # require_relative "rbnput/mouse"
 
 # The main Rbnput module
+# โมดูลหลักสำหรับ Rbnput
 #
 # This module imports keyboard and mouse submodules for controlling
 # and monitoring input devices.
+# โมดูลนี้จะนำเข้าโมดูลย่อยของคีย์บอร์ดและเมาส์เพื่อควบคุมและตรวจสอบอุปกรณ์อินพุต
 module Rbnput
+  # กำหนด Listener เป็น DarwinListener สำหรับระบบ macOS
   Listener = ::Rbnput::DarwinListener
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rbnput-darwin-minimal
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Krist Ponpairin
@@ -29,7 +29,8 @@ email:
 - krist7599555@gmail.com
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
 files:
 - LICENSE
 - README.md