wxruby3 0.9.2 → 0.9.4

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/extra/14_config.md

@@ -0,0 +1,101 @@
+<!--
+# @markup markdown
+# @title 14. Configuration support
+-->
+
+# 14. Configuration support
+
+## Introduction
+
+wxRuby3 fully supports the wxWidgets config classes providing a Ruby-fied interface.
+
+The config classes provide a way to store some application configuration information providing features
+that make them very useful for storing all kinds of small to medium volumes of hierarchically-organized, 
+heterogeneous data.
+In wxWidgets these were especially designed for storing application configuration information and intended to be 
+mostly limited to that. That meant the information to be stored was intended to be:
+
+* Typed, i.e. strings, booleans or numbers for the moment. You cannot store binary data, for example.
+* Small. For instance, it is not recommended to use the Windows registry (which is the default storage medium on 
+  that platform) for amounts of data more than a couple of kilobytes.
+* Not performance critical, neither from speed nor from a memory consumption point of view.
+
+As you will see wxRuby3 extends the support in this area and provides means to forego a lot of these restrictions.
+
+The config classes also are intended to abstract away a lot of platform differences. In this area wxRuby3 extends the
+support also.
+
+## Default configuration support
+
+When the default, global, config instance is used (by using {Wx::ConfigBase.get} with default argument) this will be 
+a platform specific instance. On Windows platforms a Windows registry based implementation is used and on other 
+platforms a text format configuration file.
+
+wxRuby3 provides a single wrapper class for these with {Wx::ConfigWx}. This is an abstract class that cannot be 
+instantiated in Ruby which provides a common, Ruby-fied interface supported by all config classes in wxRuby3.
+
+While wxWidgets does a decent job of abstracting platform differences it is in no way perfect in this area. With the
+text format configuration files for example the stored values loose all type information since everything is stored
+as strings. This also differs from the registry based implementation where some type information is not lost but some
+(like boolean types) is.
+This is not a problem when accessing information for which the structure and types are exactly known as the config
+classes offer type specific readers (as well as writers) which coerce values to their expected types but may offer 
+nasty surprises when more reflectively accessing data of which the exact typing and structure is not known.
+
+In Ruby where we more or less expect to have common API-s that can return or accept any type of object needing to be
+type specific is awkward. wxRuby3 works around this as much as possible for the {Wx::ConfigWx} wrapper class but also
+provides an alternative config class integrated with the wxWidgets framework that does not suffer from these restrictions.
+
+## Enhanced Ruby configuration support
+
+Instead of the default, platform specific, config classes it is also possible to use a custom wxRuby3 extension providing
+a config class which is implemented in pure Ruby and integrated in the wxWidgets configuration framework.
+To use an instance of this class as the global config instance the {Wx::ConfigBase.create} should be called at application
+initialization time with it's `:use_hash_config` keyword argument set to `true` (and possibly, to be sure, it's 
+`forced_create` argument set to `true` also). This would create an instance of {Wx::Config} and install that as the global config instance (if no other instance was
+yet installed or, overruling that condition, if `forced_create` was set to `true`).<br>
+Alternatively a {Wx::Config} (or derivative) instance could be explicitly instantiated in code and assigned as global 
+instance with {Wx::ConfigBase.set}.
+
+As the keyword argument indicates {Wx::Config} is a Ruby `Hash` based config class implementation. 
+
+Value objects are stored Ruby-style as-is into it's internal hash table (maintaining full type information) and are also 
+retrieved as-is by default (to maintain compatibility with the {Wx::ConfigWx} wrapper type coercion options are provided). 
+Grouping is based of nested `Hash` instances.
+
+Because of the `Hash` based implementation and lack of (the need for) type coercion the {Wx::Config} class does have **any**
+restrictions of the type of data stored. The only possible type restrictions to enforce may come from usage contexts:
+
+* In case of value entries shared with wxWidgets framework code (like for example entries save by the persistence 
+framework; see [here](15_persistence.md)) value types should be restricted to those supported by the wxWidget platform
+specific classes and correspond to what the framework code expects.
+* In case of the need to save/restore the configuration data to/from persistent storage which imposes type restrictions these 
+should be applied.
+
+With {Wx::Config} it would be perfectly alright to store arrays or any kind of arbitrary object (only be aware that `Hash`
+instances will always be expected to provide configuration structure by default) as long as these do not conflict with
+expectations of framework code or storage mechanisms.
+
+With the standard Ruby YAML and JSON serialization support this also provides improved platform independent configuration 
+persistence options with full type information maintainability. 
+
+## Differences between default and enhanced configuration support
+
+The major difference is, as described above, the absence of type restrictions in the enhanced Ruby config class {Wx::Config}.
+
+Another difference is that {Wx::Config} will not automatically create missing groups or entries on reading. This will only
+happen when writing configuration values.
+
+A last difference is that the default support is by default backed up by persistent storage (windows registry or file) and
+the wxRuby enhanced support only provides in-memory storage (`Hash` instance) by default. +
+Persisting configuration data from {Wx::Config} will require coding customized storage and retrieval operations (which is
+trivial using standard YAML or JSON support).  
+
+## Differences between wxWidgets config interface and wxRuby
+
+In wxRuby there is no option to provide a default value argument when reading values. The reasoning is that Ruby itself
+provides more than enough options to elegantly provide for defaults with statement options like `var ||= default` or
+`var = get('something') || default`.
+
+As a consequence wxRuby also does not support recording defaults on read operations (and also does not provide the
+corresponding option setter/getter in the interface).

data/lib/wx/doc/extra/15_persistence.md

@@ -0,0 +1,148 @@
+<!--
+# @markup markdown
+# @title 15. Persistence support
+-->
+
+# 15. Persistence support
+
+## Introduction
+
+wxRuby3 fully supports the wxWidgets persistence framework.
+
+This framework provides the means to persist window (and other object) states which can than be restored when
+re-creating these objects.
+
+The persistence framework depends on the configuration framework (see [here](14_config.md)).
+
+The persistence framework includes the following components:
+
+* {Wx::PersistenceManager} which all persistent objects register themselves with. This class handles actual saving 
+  and restoring of persistent data.
+* Persistent object adapters for persistent objects. These adapters provide a bridge between the associated class – 
+which has no special persistence support – and {Wx::PersistenceManager}. All Persistent object adapters need to derive 
+from {Wx::PersistentObject} (like {Wx::PersistentWindowBase} and it's derivatives).
+* The {Wx.create_persistent_object} and {Wx.persistent_register_and_restore} methods (mainly convenience methods for 
+wxWidgets compatibility).
+
+## Persistence manager
+
+By default a global singleton manager instance is available through {Wx::PersistenceManager.get} which will be used
+by all available persistent object adapters for saving/restoring state values.
+
+An alternate (possibly customized) manager instance can be installed through {Wx::PersistenceManager.set}.
+
+## Persistent object adapters
+
+All persistent object adapters must be derived from {Wx::PersistentObject}. This class provides common methods for
+saving and restoring state values connecting to the persistence manager for actual writing and reading.
+
+All windows/objects to be persisted need to be registered with the persistence manager. Creating the correct persistent
+object adapter instance for an object to persist is abstracted away in wxWidgets by using template methods allowing
+to simply only provide the object to persist instead of having to explicitly instantiate an adapter instance and provide
+both to the persistence manager (which is however still possible).
+
+wxRuby3 replaces this convenience interface (incompatible with Ruby) by a Ruby-fied approach which relies on Rubies 
+trusted *duck typing*.<br>
+In wxRuby3 any class supported by a specific persistent object adapter class should implement the method 
+`#create_persistent_object` which should return a unique adapter instance for the object instance to be persisted 
+like this:
+
+```ruby
+class MyPersistentObject < Wx::PersistentObject
+
+  # Save the object properties.
+  # The implementation of this method should use {Wx::PersistentObject#save_value}.
+  # @return [void]
+  def save
+    # ...
+  end
+
+  # Restore the object properties.
+  # The implementation of this method should use {Wx::PersistentObject#restore_value}.
+  # @return [Boolean]
+  def restore
+    # ...
+  end
+
+  # Returns the string uniquely identifying the objects supported by this adapter.
+  # This method has default implementations in any of the built-in derived adapter classes.
+  # @return [String]
+  def get_kind
+    'MyObject'
+  end
+
+  # Returns the string uniquely identifying the object we're associated with among all the other objects of the same type.
+  # This method has a default implementation in Wx::PersistentWindowBase returning the window name.
+  # @return [String]
+  def get_name
+    'object_1'
+  end
+
+end
+
+class MyObject
+  
+  # ...
+  
+  def create_persistent_object
+    MyPersistentObject.new(self)
+  end
+  
+  # ...
+  
+end
+```
+
+## Persistent windows
+
+A number of classes provide built-in support for persistence of a number of windows or controls:
+
+* {Wx::PersistentTLW} supports top level windows (including {Wx::Frame} and {Wx::Dialog}).
+* {Wx::PersistentBookCtrl} supports the book controls {Wx::Notebook}, {Wx::Listbook}, {Wx::Toolbook} and {Wx::Choicebook}.
+* {Wx::PersistentTreeBookCtrl} supports {Wx::Treebook}
+
+All persistent window adapters are derived from {Wx::PersistentWindowBase}. This class makes sure that any window 
+registered for persisting gets automatically saved when the window is destroyed. Intermittently explicit saving still
+remains possible of course.
+
+User defined persistent window adapters can be derived from this class or any of the built-in derivatives to support
+otherwise unsupported or custom windows/controls like this:
+
+```ruby
+class PersistentButton < Wx::PersistentWindowBase
+
+  def get_kind
+    'Button'
+  end
+    
+  def save
+    save_value('w', get.size.width)
+    save_value('h', get.size.height)
+    save_value('label', get.label)
+    save_value('my_custom_value', get.my_custom_value)
+  end
+    
+  def restore
+    get.size = [Integer(restore_value('w')), Integer(restore_value('h'))]
+    get.label = restore_value('label')
+    get.my_custom_value = Float(restore_value('my_custom_value'))
+    true
+  end
+
+end
+
+class MyButton < Wx::Button
+
+  def initialize(parent=nil, name)
+    super(parent, label: '', name: name)
+    @my_custom_value = ''
+  end
+
+  attr_accessor :my_custom_value
+
+  def create_persistent_object
+    PersistentButton.new(self)
+  end
+
+end
+```

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