wxruby3 0.9.3 → 0.9.5

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/owner_drawn_combobox.rb

@@ -7,7 +7,11 @@
 
 module Wx
 
-  class OwnerDrawnComboBox
+  class OwnerDrawnComboBox < ComboCtrl
+
+    alias :get_item_data :get_client_object
+
+    alias :set_item_data :set_client_object
 
     # Returns the label of the selected item or an empty string if no item is selected.
     #

data/lib/wx/doc/persistence_manager.rb

@@ -0,0 +1,36 @@
+# :stopdoc:
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+# :startdoc:
+
+
+module Wx
+
+  # Function used to create the correct persistent adapter for the given object.
+  #
+  # This is a compatibility function that simply redirects the call to the object itself. Any object class
+  # supporting persistence should implement the #create_persistent_object method to return a Wx::PersistentObject
+  # instance for the object it is called for.
+  # This method raises a NoImplementError if the object class does not support persistence.
+  # @see Defining Custom Persistent Windows
+  # @param obj [Object]
+  # @return [Wx::PersistentObject]
+  def self.create_persistent_object(obj) end
+
+  # A shorter synonym for {Wx::PersistenceManager#register_and_restore}.
+  #
+  # This function simply calls {Wx::PersistenceManager#register_and_restore} but using it results in slightly shorter
+  # code as it calls {Wx::PersistenceManager.get} internally. As an additional convenience, this function can also set the window name.
+  #
+  # Returns true if the settings were restored or false otherwise (this will always be the case when the program runs
+  # for the first time, for example).
+  # @param obj [Wx::Window]  window to register with persistence manager and to try to restore the settings for.
+  # @param name [String]  If specified non-empty, window name is changed to the provided value before registering it.
+  # @return [Boolean]
+  def self.persistent_register_and_restore(obj, name=nil) end
+
+  # class alias
+  PersistentWindow = PersistentWindowBase
+
+end

data/lib/wx/doc/persistent_object.rb

@@ -0,0 +1,27 @@
+# :stopdoc:
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+# :startdoc:
+
+
+module Wx
+
+  class PersistentObject < ::Object
+
+    # Save the specified value using the given name.
+    # @param [String] name The name of the value in the configuration file.
+    # @param [Object] value The value to save, currently must be a type supported by wxConfig.
+    # @return [Boolean] true if the value was saved or false if an error occurred.
+    def save_value(name, value); end
+    protected :save_value
+
+    # Restore a value saved by {#save_value}.
+    # @param [String] name The name of the value in the configuration file.
+    # @return [Object,nil] The value if successfully read, nil otherwise
+    def restore_value(name); end
+    protected :restore_value
+
+  end
+
+end

data/lib/wx/doc/top_level_window.rb

@@ -0,0 +1,19 @@
+# :stopdoc:
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+# :startdoc:
+
+
+module Wx
+
+  class TopLevelWindow < NonOwnedWindow
+
+    # Creates PersistentObject for this toplevel window instance (incl. Dialog and Frame).
+    # @see Wx.create_persistent_object
+    # @return [Wx::PersistentTLW]
+    def create_persistent_object; end
+
+  end
+
+end

data/lib/wx/doc/treebook.rb

@@ -7,13 +7,18 @@
 
 module Wx
 
-  class Treebook
+  class Treebook < BookCtrlBase
 
     # Returns the Wx::TreeCtrl used for this Treebook
     # @return [Wx::TreeCtrl] the tree control
     def get_tree_ctrl; end
     alias :tree_ctrl :get_tree_ctrl
 
+    # Creates PersistentObject for this treebook control instance.
+    # @see Wx.create_persistent_object
+    # @return [Wx::PersistentTreeBookCtrl]
+    def create_persistent_object; end
+
   end
 
 end

data/lib/wx/version.rb

@@ -3,5 +3,5 @@
 # This software is released under the MIT license.
 
 module Wx
-  WXRUBY_VERSION    = '0.9.3'
+  WXRUBY_VERSION    = '0.9.5'
 end

data/rakelib/build.rb

@@ -48,7 +48,7 @@ if WXRuby3.is_bootstrapped?
       end
 
       # The main source module - which needs to initialize all the other modules in the package
-      file pkg.initializer_src => pkg.all_swig_files do |t|
+      file pkg.initializer_src => (pkg.all_swig_files + (pkg.parent ? [pkg.parent.initializer_src] : [])) do |t|
         pkg.generate_initializer
       end
 

data/rakelib/lib/core/include/funcall.inc

@@ -22,7 +22,8 @@ namespace Swig
     DirectorRubyException(VALUE error, VALUE rcvr, ID fn_id)
       : DirectorException(Qnil)
     {
-      VALUE msg = rb_sprintf("Caught exception in SWIG director method for %s#%s", rb_class2name(CLASS_OF(rcvr)), rb_id2name(fn_id));
+      VALUE msg = rb_sprintf("Caught exception in SWIG director method for %s#%s : ", rb_class2name(CLASS_OF(rcvr)), rb_id2name(fn_id));
+      rb_str_append(msg, rb_funcall(error, rb_intern("message"), 0));
       this->swig_msg = StringValuePtr(msg);
       swig_error = rb_exc_new_str(rb_eRuntimeError, msg);
       VALUE bt = rb_funcall(error, rb_intern("backtrace"), 0);

data/rakelib/lib/core/package.rb

@@ -6,6 +6,8 @@
 # wxRuby3 extension library Package class
 ###
 
+require 'monitor'
+
 module WXRuby3
 
   class Director
@@ -434,9 +436,29 @@ module WXRuby3
         def generated_events
           @generated_events ||= ::Set.new
         end
+
+        def event_list_packages
+          unless @event_list_packages
+            @event_list_packages = ::Set.new
+            @event_list_packages.extend(MonitorMixin)
+          end
+          @event_list_packages
+        end
       end
 
       def generate_event_list
+        # make sure parent package has already generated event list
+        Package.event_list_packages.synchronize do
+          if parent && !Package.event_list_packages.include?(parent)
+            # make sure all included director modules have been extracted
+            parent.included_directors.each do |dir|
+              dir.extract_interface(false) # no need to generate anything here
+            end
+            parent.generate_event_list
+          end
+        end
+        # list ourselves as generated
+        Package.event_list_packages << self
         # determine Ruby library events root for package
         rbevt_root = File.join(ruby_classes_path, 'events')
         # create event list file
@@ -483,7 +505,6 @@ module WXRuby3
           fout.puts 'end'
         end
       end
-      private :generate_event_list
 
       def find_event_doc(evh_name)
         unless doc = event_docs[evh_name]

data/rakelib/lib/core/spec.rb

@@ -272,6 +272,16 @@ module WXRuby3
         self
       end
 
+      def gc_as_marked(*names)
+        if names.empty?
+          @gc_type = :GC_MANAGE_AS_MARKED
+        else
+          @gc_type = ::Hash.new unless @gc_type.is_a?(::Hash)
+          names.flatten.each {|n| @gc_type[n] = :GC_MANAGE_AS_MARKED }
+        end
+        self
+      end
+
       def gc_type(name)
         @gc_type.is_a?(::Hash) ? @gc_type[name] : @gc_type
       end

data/rakelib/lib/core/spec_helper.rb

@@ -121,7 +121,7 @@ module WXRuby3
 
     def get_base_module_list(hierarchy, foldedbases, list = ::Set.new)
       hierarchy.each_value do |super_def|
-        list << super_def.module unless foldedbases.include?(super_def.name)
+        list << super_def.module unless foldedbases.include?(super_def.name) || super_def.module == module_name
         get_base_module_list(super_def.supers, folded_bases(super_def.name), list)
       end
       list

data/rakelib/lib/director/comboctrl.rb

@@ -14,9 +14,10 @@ module WXRuby3
 
     class ComboCtrl < Window
 
+      include Typemap::ComboPopup
+
       def setup
         super
-        spec.items << 'wxComboPopup'
         # mixin TextEntry
         spec.include_mixin 'wxComboCtrl', { 'Wx::TextEntry' => 'wxTextEntryBase' }
         spec.override_inheritance_chain('wxComboCtrl',
@@ -29,8 +30,108 @@ module WXRuby3
           wxComboCtrl::DoSetPopupControl
           wxComboCtrl::DoShowPopup
         ]
-        # turn wxComboPopup into a mixin module
-        spec.make_mixin 'wxComboPopup'
+        spec.add_header_code <<~__HEREDOC
+          #include "wxruby-ComboPopup.h"
+
+          static VALUE g_rb_mWxComboPopup = Qnil;
+          static VALUE g_rb_cComboPopupWx = Qnil;
+
+          WXRUBY_EXPORT wxComboPopup* wxRuby_ComboPopupFromRuby(VALUE popup)
+          {
+            if (!NIL_P(popup) && !rb_obj_is_kind_of(popup, g_rb_mWxComboPopup))
+            {
+              rb_raise(rb_eArgError, "Expected a Wx::ComboPopup or nil for 1");
+              return nullptr;
+            }
+
+            wxComboPopup* cpp = nullptr; 
+            if (!NIL_P(popup))
+            {
+              VALUE rb_cp_proxy = rb_iv_get(popup, "@_wx_combo_popup_proxy");
+              if (NIL_P(rb_cp_proxy))
+              {
+                cpp = new WxRubyComboPopup(popup);
+                rb_cp_proxy = Data_Wrap_Struct(rb_cObject, 0, 0, cpp);
+                rb_iv_set(popup, "@_wx_combo_popup_proxy", rb_cp_proxy);
+              }
+              else
+              {
+                Data_Get_Struct(rb_cp_proxy, wxComboPopup, cpp);
+              }
+            }
+            return cpp;
+          }
+
+          WXRUBY_EXPORT VALUE wxRuby_ComboPopupToRuby(wxComboPopup* cpp)
+          {
+            VALUE rb_cpp = Qnil;
+            if (cpp)
+            {
+              WxRubyComboPopup *wxrb_cpp = dynamic_cast<WxRubyComboPopup*> (cpp);
+              if (wxrb_cpp)
+              {
+                rb_cpp = wxrb_cpp->GetRubyComboPopup();
+              }
+              else
+              {
+                // in this case we're probably working for a wxOwnerDrawnComboBox or wxRichTextListbox 
+                // with default popup control which is a C++ implemented class without any Ruby linkage.
+                // wrap this in the Wx::ComboPopupWx class to provide a Ruby interface
+                rb_cpp = Data_Wrap_Struct(g_rb_cComboPopupWx, 0, 0, cpp); // do not own or track
+              }
+            }
+            return rb_cpp;
+          }
+
+          static void wxRuby_markComboPopups()
+          {
+            WxRubyComboPopup::GC_mark_combo_popups();
+          }
+          __HEREDOC
+        # ignore these
+        spec.ignore 'wxComboCtrl::SetPopupControl',
+                    'wxComboCtrl::GetPopupControl',
+                    ignore_doc: false
+        # for GetPopupControl docs only
+        spec.map 'wxComboPopup*' => 'Wx::ComboPopup', swig: false do
+          map_out code: ''
+        end
+        # and replace
+        spec.add_extend_code 'wxComboCtrl', <<~__HEREDOC
+          void SetPopupControl(VALUE popup)
+          {
+            wxComboPopup* cpp = wxRuby_ComboPopupFromRuby(popup);
+            $self->SetPopupControl(cpp);
+          }
+      
+          VALUE GetPopupControl()
+          {
+            return wxRuby_ComboPopupToRuby($self->GetPopupControl());
+          }
+          __HEREDOC
+        spec.add_init_code <<~__HEREDOC
+          wxRuby_AppendMarker(wxRuby_markComboPopups);
+
+          g_rb_mWxComboPopup = rb_define_module_under(mWxCore, "ComboPopup");
+          rb_define_method(g_rb_mWxComboPopup, "get_combo_ctrl", VALUEFUNC(wx_combo_popup_get_combo_ctrl), -1);
+
+          g_rb_cComboPopupWx = rb_define_class_under(mWxCore, "ComboPopupWx", rb_cObject);
+          rb_undef_alloc_func(g_rb_cComboPopupWx);
+          rb_define_method(g_rb_cComboPopupWx, "lazy_create", VALUEFUNC(combo_popup_wx_lazy_create), -1);
+          rb_define_method(g_rb_cComboPopupWx, "create", VALUEFUNC(combo_popup_wx_create), -1);
+          rb_define_method(g_rb_cComboPopupWx, "get_combo_ctrl", VALUEFUNC(combo_popup_wx_get_combo_ctrl), -1);
+          rb_define_method(g_rb_cComboPopupWx, "find_item", VALUEFUNC(combo_popup_wx_find_item), -1);
+          rb_define_method(g_rb_cComboPopupWx, "get_adjusted_size", VALUEFUNC(combo_popup_wx_get_adjusted_size), -1);
+          rb_define_method(g_rb_cComboPopupWx, "get_control", VALUEFUNC(combo_popup_wx_get_control), -1);
+          rb_define_method(g_rb_cComboPopupWx, "set_string_value", VALUEFUNC(combo_popup_wx_set_string_value), -1);
+          rb_define_method(g_rb_cComboPopupWx, "get_string_value", VALUEFUNC(combo_popup_wx_get_string_value), -1);
+          rb_define_method(g_rb_cComboPopupWx, "on_combo_double_click", VALUEFUNC(combo_popup_wx_on_combo_double_click), -1);
+          rb_define_method(g_rb_cComboPopupWx, "on_combo_key_event", VALUEFUNC(combo_popup_wx_on_combo_key_event), -1);
+          rb_define_method(g_rb_cComboPopupWx, "on_combo_char_event", VALUEFUNC(combo_popup_wx_on_combo_char_event), -1);
+          rb_define_method(g_rb_cComboPopupWx, "on_dismiss", VALUEFUNC(combo_popup_wx_on_dismiss), -1);
+          rb_define_method(g_rb_cComboPopupWx, "on_popup", VALUEFUNC(combo_popup_wx_on_popup), -1);
+          rb_define_method(g_rb_cComboPopupWx, "paint_combo_control", VALUEFUNC(combo_popup_wx_paint_combo_control), -1);
+          __HEREDOC
       end
 
     end # class ComboCtrl