wxruby3 0.9.2-x64-mingw-ucrt → 0.9.4-x64-mingw-ucrt

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/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