wxruby3 0.9.2 → 0.9.3

data/lib/wx/core/text_entry.rb

@@ -13,7 +13,10 @@ module Wx
     wx_auto_complete = instance_method :auto_complete
     define_method :auto_complete do |completer|
       if wx_auto_complete.bind(self).call(completer)
-        @completer = completer # keep the Ruby object alive
+        @completer = completer.is_a?(Wx::TextCompleter) ? completer : nil # keep the Ruby object alive or cleanup
+        true
+      else
+        false
       end
     end
 

data/lib/wx/core/validator.rb

@@ -1,15 +1,80 @@
 # Copyright (c) 2023 M.J.N. Corino, The Netherlands
 #
 # This software is released under the MIT license.
-# 
-# Some parts are
-# Copyright 2004-2007, wxRuby development team
-# released under the MIT-like wxRuby2 license
 
 class Wx::Validator
+
   # Default implementation of clone, may need to be over-ridden if
   # custom subclasses should state variables that need to be copied
+  # NOTE: There is no way to copy the bindings here so do NOT
   def clone
-    self.class.new
+    begin
+      self.class.new(self)
+    rescue
+      p $!
+      raise
+    end
+  end
+
+  # overload for customized functionality
+  def do_transfer_from_window
+    nil # by default just return nil
   end
+  protected :do_transfer_from_window
+
+  # overload for customized functionality
+  def do_transfer_to_window(_data)
+    true # by default just return true
+  end
+  protected :do_transfer_to_window
+
+  protected :do_on_transfer_from_window
+  protected :do_on_transfer_to_window
+
+  module Binding
+    def self.included(base)
+      wx_on_transfer_from_window = base.instance_method :on_transfer_from_window
+      base.define_method :on_transfer_from_window do |meth = nil, &block|
+        proc = if block and not meth
+                 block
+               elsif meth and not block
+                 h_meth = case meth
+                          when Symbol, String then self.method(meth)
+                          when Proc then meth
+                          when Method then meth
+                          end
+                 # check arity == 1
+                 if h_meth.arity != 1
+                   Kernel.raise ArgumentError,
+                                "on_transfer_from_window handler should accept a single argument"
+                 end
+                 h_meth
+               end
+        wx_on_transfer_from_window.bind(self).call(proc)
+      end
+
+      wx_on_transfer_to_window = base.instance_method :on_transfer_to_window
+      base.define_method :on_transfer_to_window do |meth = nil, &block|
+        proc = if block and not meth
+                 block
+               elsif meth and not block
+                 h_meth = case meth
+                          when Symbol, String then self.method(meth)
+                          when Proc then meth
+                          when Method then meth
+                          end
+                 # check arity == 0
+                 if h_meth.arity != 0
+                   Kernel.raise ArgumentError,
+                                "on_transfer_to_window handler should not accept any argument"
+                 end
+                 h_meth
+               end
+        wx_on_transfer_to_window.bind(self).call(proc)
+      end
+    end
+  end
+
+  include Binding
+
 end

data/lib/wx/core/window.rb

@@ -26,13 +26,9 @@ class Wx::Window
   # In case a more explicit option is preferred.
   alias :wx_id :get_id
 
-  # The name of Wx::Window#raise conflicts with Ruby's core Kernel#raise
-  # method. This can cause unexpected errors when undecorated #raise is
-  # used inside a Window method. For wxRuby 2.0 it's too late to remove
-  # Window#raise completely, but for now, offer alternatives to
-  # raise/lower that could replace them in future versions.
-  alias :bring_to_front :raise
-  alias :send_to_back :lower
+  # Z-order alternatives
+  alias :bring_to_front :raise_window
+  alias :send_to_back :lower_window
 
   # Recursively searches all windows below +self+ and returns the first
   # window which has the id +an_id+. This corresponds to the find_window

data/lib/wx/doc/art_locator.rb

@@ -59,6 +59,7 @@ module Wx
       # @param [String,nil] art_path base path to look up the art file
       # @param [String,nil] art_section optional owner folder name for art files
       # @param [Wx::BitmapType,nil] bmp_type bitmap type of art file
+      # @return [String,nil] full path of art file or nil if not found
       def find_art(art_name, art_type: nil, art_path: nil, art_section: nil, bmp_type: nil) end
 
     end

data/lib/wx/doc/comboctrl.rb

@@ -0,0 +1,18 @@
+# :stopdoc:
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+# :startdoc:
+
+
+module Wx
+
+  class OwnerDrawnComboBox < ComboCtrl
+
+    alias :get_item_data :get_client_object
+
+    alias :set_item_data :set_client_object
+
+  end
+
+end

data/lib/wx/doc/controlwithitems.rb

@@ -9,6 +9,14 @@ module Wx
 
   class ControlWithItems
 
+    alias :get_client_data :get_client_object
+
+    alias :set_client_data :set_client_object
+
+    alias :has_client_data :has_client_object_data
+
+    alias :has_client_data? :has_client_object_data
+
     # Yield each string to the given block.
     # Returns an Enumerator if no block given.
     # @yieldparam [String] string the string yielded
@@ -22,6 +30,14 @@ module Wx
     def is_sorted; end
     alias :sorted? :is_sorted
 
+    alias :get_list_selection :get_selection
+
+    alias :set_list_selection :set_selection
+
+    alias :get_list_string_selection :get_string_selection
+
+    alias :set_list_string_selection :set_string_selection
+
   end
 
 end

data/lib/wx/doc/date_picker_ctrl.rb

@@ -0,0 +1,23 @@
+# :stopdoc:
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+# :startdoc:
+
+
+module Wx
+
+  class DatePickerCtrl < Control
+
+    # If the control had been previously limited to a range of dates using #set_range, returns the lower and upper bounds of this range.
+    #
+    # If no range is set (or only one of the bounds is set), dt1 and/or dt2 are set to be invalid.
+    #
+    # Notice that when using a native MSW implementation of this control the lower range is always set, even
+    # if #set_range hadn't been called explicitly, as the native control only supports dates later than year 1601.
+    # @return [Array(Time, Time),nil] a set with the lower and upper range limit or nil if no range previously set
+    def get_range; end
+
+  end
+
+end

data/lib/wx/doc/editable_listbox.rb

@@ -0,0 +1,44 @@
+# :stopdoc:
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+# :startdoc:
+
+
+module Wx
+
+  class EditableListBox < Panel
+
+    # Returns list control of composite.
+    # @return [Wx::ListCtrl]
+    def get_list_ctrl; end
+    alias :list_ctrl :get_list_ctrl
+
+    # Returns button of composite.
+    # @return [Wx::BitmapButton]
+    def get_del_button; end
+    alias :del_button :get_del_button
+
+    # Returns button of composite.
+    # @return [Wx::BitmapButton]
+    def get_new_button; end
+    alias :new_button :get_new_button
+
+    # Returns button of composite.
+    # @return [Wx::BitmapButton]
+    def get_up_button; end
+    alias :up_button :get_up_button
+
+    # Returns button of composite.
+    # @return [Wx::BitmapButton]
+    def get_down_button; end
+    alias :down_button :get_down_button
+
+    # Returns button of composite.
+    # @return [Wx::BitmapButton]
+    def get_edit_button; end
+    alias :edit_button :get_edit_button
+
+  end
+
+end

data/lib/wx/doc/enum.rb

@@ -68,6 +68,21 @@ module Wx
     # @return [Boolean]
     def !; end
 
+    # Returns true if all bits that are set (=1) in mask are also set in self; returns false otherwise.
+    # @param [Integer] mask
+    # @return [Boolean]
+    def allbits?(mask) end
+
+    # Returns true if any bit that is set (=1) in mask is also set in self; returns false otherwise.
+    # @param [Integer] mask
+    # @return [Boolean]
+    def anybits?(mask) end
+
+    # Returns true if no bit that is set (=1) in mask is also set in self; returns false otherwise.
+    # @param [Integer] mask
+    # @return [Boolean]
+    def nobits?(mask) end
+
     # Return next integer value from enum's value.
     # @return [Integer] next integer value
     def succ; end

data/lib/wx/doc/event.rb

@@ -27,4 +27,16 @@ module Wx
 
   end
 
+  class CommandEvent < Event
+
+    alias :set_client_data :set_client_object
+
+    alias :client_data= :set_client_object
+
+    alias :get_client_data :get_client_object
+
+    alias :client_data :get_client_object
+
+  end
+
 end

data/lib/wx/doc/extra/12_client_data.md

@@ -0,0 +1,89 @@
+<!--
+# @markup markdown
+# @title 12. Client/User data with wxRuby
+-->
+
+# 12. Client/User data with wxRuby
+
+## Introduction
+
+The wxWidgets library has widespread support for attaching arbitrary client (or user) data to GUI elements like
+windows (all event handlers actually), window items, sizer items etc.
+To cater to various C++ use cases in most instances this support covers both specific wxWidgets defined types (like
+wxClientData and wxObject instances) and untyped data pointers (represented as `void *`) with subtle but essential
+differences.
+
+wxRuby implements a fully compatible version of this support.    
+
+## Everything is an Object
+
+As Ruby does not do untyped data (everything is an Object), and having two different options is confusing anyway, 
+wxRuby provides only a single option and more or less unifies the interface across the entire library.
+In Ruby anywhere the original wxWidgets library supports some type of client (or user) data attachment wxRuby will 
+support the attachment of any arbitrary Ruby `Object` by either the method `#set_client_object` (where C++ supports 
+`SetClientData` and `SetClientObject`) or `#set_user_data` (where C++ supports `SetUserData`). Data retrieval
+is supported by complementary `#get_client_object` or `#get_user_data` methods in all cases.
+Wherever C++ supports `SetClientObject` wxRuby also provides the method aliases `#set_client_data` and `#get_client_data`.
+
+Another difference with C++ is that for typed client data in wxWidgets developers could leverage object destruction as 
+callback trigger (through the implementation of virtual destructors) to handle any required 'unlinking' logic. This
+obviously does not apply to untyped data (one of the 'subtle' differences).
+As Ruby does not provide any usable object destruction hooks this does not work there.
+Ruby however has 'Duck-typing' which is what wxRuby uses to provide support for a unlinking callback 'hook' for attached
+client data.
+
+> Any attached Ruby Object implementing (responding to) the method `#client_data_unlinked` will have that method called after the 
+> attached object has been detached from the element it was attached to (either because of data replacement or element 
+> deletion).
+
+Regard the following example.
+
+```ruby
+    frame = Wx::Frame.new(nil, Wx::ID_ANY)
+    
+    # attach a hash with user data  
+    frame.set_client_data({ text: 'A string', float: 3.14 })
+    
+    # ... do something with frame
+    
+    # replace the user data
+    frame.set_client_data([1,2,3,4])
+
+    # ... do something else with frame
+```
+
+In this case standard Ruby object are attached. After attachment the object can be retrieved using a call to `get_client_data`
+anywhere access to the frame instance is available.
+
+Using a specially derived (or adapted) object a developer can handle specific logic after the object has been unlinked 
+like in this example:
+
+```ruby
+    # define a user data class
+    class MyUserData
+      def initialize(payload)
+        @payload = payload
+      end
+      attr_reader :payload
+      
+      def client_data_unlinked
+        # handle some logic
+      end
+    end
+
+    # ...
+
+    # attach data to some window
+    win.set_client_data(MyUserData.new(some_payload_data)) 
+
+    # ...
+    
+    # reset user data for some reason (will call MyUserData#client_data_unlinked after replacement)
+    win.set_client_data(nil)
+```
+
+# CommandEvent data
+
+wxRuby also fully supports the propagation of attached client data to Wx::CommandEvent objects (see
+{Wx::CommandEvent#get_client_object} and {Wx::CommandEvent#set_client_object}).
+As mentioned above wxRuby provides the method aliases `#set_client_data` and `#get_client_data` here also. 

data/lib/wx/doc/extra/13_validators.md

@@ -0,0 +1,139 @@
+<!--
+# @markup markdown
+# @title 13. Validators and data binding
+-->
+
+# 13. Validators and data binding
+
+## Introduction
+
+wxRuby fully supports validator classes offering input validation and/or data binding and/or event filtering. 
+
+## Validation
+
+The base Wx::Validator class defines the method {Wx::Validator#validate} which is called when validation of the
+value or content of the associated window is required.
+
+The implementation of this method should (somehow) retrieve the value of the associated window and validate that
+value, returning `true` if valid or `false` otherwise. The default implementation always returns `false`.
+
+An example would be:
+
+```ruby
+# define custom validator
+class MyTextValidator < Wx::Validator
+
+  def validate(_parent)
+    txt = get_window.value
+    # validate that the control text starts with a capital if not empty
+    txt.empty? || (?A..?Z).include?(txt[0])
+  end
+
+end
+
+# ...
+
+# assign custom validator to text control
+text = Wx::TextCtrl.new(parent, MY_TEXT_ID)
+text.set_validator(MyTextValidator.new)
+```
+
+The derived, specialized, validator classes {Wx::TextValidator}, {Wx::IntegerValidator}, {Wx::IntegerValidator} and 
+{Wx::FloatValidator} all have implementations that can be configured through specific options and do not 
+normally require an override to be defined.
+
+Examples of using the standard validators would be:
+
+```ruby
+text = Wx::TextCtrl.new(parent, MY_TEXT_ID)
+
+# accept only hexadecimal characters
+text.set_validator(Wx::TextValidator.new(Wx::TextValidatorStyle::FILTER_XDIGITS))
+
+# or only numbers between -20 and 20
+text.set_validator(Wx::IntegerValidator.new(-20, 20))
+```
+
+## Event filtering
+
+All validator classes are event handlers and can have event handling routines defined (see 
+[Event Handling](05_event-handling.md)).
+When processing events the core implementation will allow any validator associated with a window to handle an event
+before the associated window itself thereby allowing it to filter events (see {Wx::EvtHandler#process_event} for more 
+details).
+
+The standard specialized validators use this functionality to filter entry of allowable characters (by handling 
+Wx::EVT_CHAR events).
+
+## Data binding
+
+Data binding concerns the transfer of a validator's associated window's value to or from a user definable storage (a 
+variable, memory cache entry, persistent storage ...).
+
+To integrate with the core C++ implementation but allow for Ruby specific differences the scheme implemented for this
+differs somewhat (in naming and functionality) from the original wxWidgets interface.
+
+The responsibilities of the standard wxRuby interface for handling validator data binding is distributed over 2 base 
+methods and a mixin module.  
+
+- The protected {Wx::Validator#do_transfer_from_window} and {Wx::Validator#do_transfer_to_window} methods are 
+  responsible for collecting and transferring data from/to the associated window (possibly applying conversions).<br>
+  <br>
+  These methods have default implementations in all of the derived validator classes and should not be overridden for
+  specializations of these as they will be ignored.<br>
+  Overriding these methods is necessary to implement data binding for any user defined specialization of the base 
+  {Wx::Validator} class.<br>
+  <br>
+- The methods the {Wx::Validator::Binding} mixin module provide the means to store data after collection from or retrieve data 
+  before transfer to the associated window.<br>
+  <br>
+  The methods {Wx::Validator::Binding#on_transfer_from_window} and {Wx::Validator::Binding#on_transfer_to_window} provide
+  the means to specify user defined binding handlers for storing the data transferred from the associated window or retrieving the
+  data to transfer to the associated window. Like with event handling the handlers can be specified using a `String` or
+  `Symbol`, a `Proc` or a `Method`.<br>
+  <br>
+  The methods {Wx::Validator::Binding#do_on_transfer_from_window} and {Wx::Validator::Binding#do_on_transfer_to_window} by
+  default call the binding handlers if defined.
+  These methods can be overridden to create derived validator classes with dedicated data binding functionality like 
+  with {Wx::GenericValidator}.
+
+An example of a custom validator providing data binding would be:
+
+```ruby
+class MyTextValidator < Wx::Validator
+
+  def do_transfer_from_window
+    get_window.get_value
+  end
+
+  def do_transfer_to_window(val)
+    get_window.set_value(val)
+    true
+  end
+  
+end
+
+# ...
+
+# use custom validator
+@data = nil # attribute to store data
+text.set_validator(MyTextValidator.new)
+text.get_validator.on_transfer_to_window { @data }
+text.get_validator.on_transfer_from_window { |v| @data = v }
+```
+
+All derived, specialized, validators implement a dedicated value cache which can be accessed through the `#value` attribute
+accessor. Through this accessor the data collected from the associated window can get retrieved or the data to be transferred
+to the associated window set.
+With these classes it is therefor not necessary to define binding handlers. Defining binding handlers can however still be 
+useful to implement a custom, persistent, storage solution.
+
+### Wx::GenericValidator
+
+The {Wx::GenericValidator} class provides an extendable standard implementation for data binding in combination with a 
+large collection of controls (see class documentation).
+The implementation provides a standard accessor {Wx::GenericValidator#value} to get the data value collected
+from the associated window or set the data to transfer to the associated window.
+
+To add support for any control unsupported by the standard implementation the method {Wx::GenericValidator.define_handler}
+is provided (see documentation for an example).

data/lib/wx/doc/gdi_common.rb

@@ -61,8 +61,12 @@ module Wx
 
     alias :get_x :get_width
     alias :x :get_width
+    alias :set_x :set_width
+    alias :x= :set_width
     alias :get_y :get_height
     alias :y :get_height
+    alias :set_y :set_height
+    alias :y= :set_height
 
     # Set this size to the given size's width,height values
     # @param [Wx::Size] sz

data/lib/wx/doc/generic_validator.rb

@@ -0,0 +1,95 @@
+# :stopdoc:
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+# :startdoc:
+
+
+module Wx
+
+  # Wx::GenericValidator performs data transfer (but not validation or filtering)
+  # for many type of controls.
+  #
+  # Wx::GenericValidator supports:
+  # - boolean type controls
+  #   - Wx::CheckBox, Wx::RadioButton, Wx::ToggleButton, Wx::BitmapToggleButton
+  # - string type controls
+  #   - Wx::Button, Wx::StaticText, Wx::TextCtrl
+  #   - Wx::ComboBox in case it does not have style Wx::CB_READONLY
+  # - integer type controls
+  #   - Wx::RadioBox, Wx::SpinButton, Wx::SpinCtrl, Wx::Gauge, Wx::Slider, Wx::ScrollBar, Wx::Choice
+  #   - Wx::ComboBox in case it has style Wx::CB_READONLY
+  #   - Wx::ListBox and Wx::CheckListBox in case of style Wx::LB_SINGLE
+  # - integer array type controls
+  #   - Wx::ListBox and Wx::CheckListBox in case of style Wx::LB_MULTIPLE or Wx::LB_EXTENDED
+  # - date/time type controls
+  #   - Wx::DatePickerCtrl, Wx::TimePickerCtrl
+  #
+  # It checks the type of the window and uses an appropriate type for it.
+  # For example, Wx::Button and Wx::TextCtrl transfer data to and from a
+  # String variable; Wx::ListBox uses an Array of Integer (in case of multiple
+  # selection list) or an Integer (in case of a single choice list); Wx::CheckBox
+  # uses a boolean.
+  #
+  # In wxRuby this is a pure Ruby implementation derived from Wx::Validator and
+  # **not** a wrapper for the C++ wxGenericValidator class although the functionality
+  # is virtually identical.
+  #
+  # @see  Wx::Validator
+  # @see  Wx::TextValidator
+  # @see  Wx::IntegerValidator
+  # @see  Wx::UnsignedValidator
+  # @see  Wx::FloatValidator
+  #
+  # @wxrb_require USE_VALIDATORS
+  class GenericValidator < Wx::Validator
+
+    # Returns a Hash of handlers for the various control types this class supports.
+    # User defined extension (or re-definition) of these handlers is possible.
+    # @see GenericValidator.define_handler
+    # @return [Hash]
+    def self.handlers; end
+
+    # Defines a new handler for a control type (class).
+    #
+    # When called it should be supplied the control Class and either a Proc or Method
+    # instance or a block which should accept a single Wx::Window argument and an optional
+    # second argument.
+    # The handler will be called when transferring data from or to the associated window.
+    # The associated window is always passed as the first argument.
+    # In case of a transfer from the associated window that is the only argument and the
+    # handler should retrieve and return the data typical for the type of control window.
+    # In case of a transfer to the associated window the second argument will be the data
+    # to transfer to the associated control window.
+    #
+    # @example Definition of Wx::TextCtrl handler
+    #   GenericValidator.define_handler(Wx::TextCtrl) do |win, *val|
+    #     if val.empty?
+    #       win.get_value
+    #     else
+    #       win.set_value(val.shift)
+    #     end
+    #   end
+    #
+    # @param [Class] klass control window class
+    # @param [Proc,Method,nil] meth
+    # @return [void]
+    def self.define_handler(klass, meth=nil, &block) end
+
+    # @overload initialize
+    #   Default constructor.
+    #   @return [Wx::GenericValidator]
+    # @overload initialize(other)
+    #   Copy constructor.
+    #   @param [Wx::GenericValidator] other
+    #   @return [Wx::GenericValidator]
+    def initialize(*arg)end
+
+    # The value store attribute. Initially nil. When set the type should
+    # be appropriate for the associated control type.
+    # No forced conversions will be applied.
+    attr_accessor :value
+
+  end
+
+end

data/lib/wx/doc/html/simple_html_listbox.rb

@@ -0,0 +1,22 @@
+# :stopdoc:
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+# :startdoc:
+
+
+class Wx
+
+  module HTML
+
+    class SimpleHtmlListBox
+
+      alias :get_client_data :get_client_object
+
+      alias :set_client_data :set_client_object
+
+    end
+
+  end
+
+end