wxruby3 0.9.0.pre.rc.2 → 0.9.0

data/rakelib/lib/generate/doc/symbol_picker_dialog.yaml

@@ -0,0 +1,40 @@
+---
+:wxSymbolPickerDialog:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              ctrl = find_window(ID_RICHTEXT_CTRL)
+              
+              attr = Wx::TextAttr.new
+              attr.set_flags(Wx::TEXT_ATTR_FONT)
+              ctrl.get_style(ctrl.insertion_point, attr)
+              
+              if attr.has_font? && attr.font.ok?
+                currentFontName = attr.font.face_name
+              
+              # Don't set the initial font in the dialog (so the user is choosing
+              # 'normal text', i.e. the current font) but do tell the dialog
+              # what 'normal text' is.
+              
+              Wx.SymbolPickerDialog("*", '', currentFontName, self) do |dlg|
+              
+                if dlg.show_modal == Wx::ID_OK
+                  if dlg.has_selection?
+                    insertionPoint = ctrl.insertion_point
+            
+                    ctrl.write_text(dlg.symbol)
+            
+                    unless dlg.use_normal_font
+                      font = attr.font
+                      font.face_name = dlg.font_name
+                      attr.font = font
+                      ctrl.set_style(insertionPoint, insertionPoint+1, attr)
+                    end
+                  end
+                end
+              end
+            ```

data/rakelib/lib/generate/doc/text_ctrl.yaml

@@ -0,0 +1,19 @@
+---
+:wxTextCtrl:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /SetDefaultStyle.*wxRED/
+          :replace: |
+            
+            ```ruby
+              text.set_default_style(Wx::TextAttr.new(Wx::RED))
+              text.append_text("Red text\n")
+              text.set_default_style(Wx::TextAttr.new(Wx::NULL_COLOUR, Wx::LIGHT_GREY))
+              text.append_text("Red on grey text\n")
+              text.set_default_style(Wx::TextAttr.new(Wx::BLUE))
+              text.append_text("Blue on grey text\n")
+            ```
+    :post:
+      - :pattern: !ruby/regexp /==\s+wxTextCtrl\s+and\s+C\+\+\s+Streams.*See\s+\{Wx::StreamToTextRedirector\}\s+for\s+more\s+details\./m
+        :subst: ''

data/rakelib/lib/generate/doc/text_entry.yaml

@@ -0,0 +1,42 @@
+---
+:wxTextEntry.GetInsertionPoint:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              def get_current_char(txt_ctrl)
+                 pos = txt_ctrl.get_insertion_point
+                 return '' if pos == txt_ctrl.get_last_position
+              
+                 txt_ctrl.get_range(pos, pos + 1)
+              end
+            ```
+:wxTextCompleterSimple:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              class MyTextCompleter < Wx::TextCompleterSimple
+            
+                def get_completions(prefix)
+                  firstWord = prefix.split(' ').shift
+                  if firstWord == 'white'
+                    ['white pawn', 'white rook']
+                  elsif firstWord == 'black'
+                    ['black king', 'black queen']
+                  else
+                    ['white', 'black']
+                  end
+                end
+            
+              end
+              ...
+              text_ctrl = ...
+              text_ctrl.auto_complete(MyTextCompleter.new)
+            ```

data/rakelib/lib/generate/doc/text_entry_dialog.yaml

@@ -0,0 +1,17 @@
+---
+:wxTextEntryDialog.SetTextValidator:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              Wx::TextEntryDialog(self, ...) do |dlg|
+                dlg.set_text_validator(Wx::FILTER_ALPHA)
+                if dlg.show_modal == Wx::ID_OK
+                   # We can be certain that this string contains letters only.
+                   value = dlg.get_value
+                end
+              end
+            ```

data/rakelib/lib/generate/doc/timer_event.yaml

@@ -0,0 +1,28 @@
+---
+:wxTimerEvent:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              class MyFrame < Wx::Frame
+
+                def initialize
+                  super(nil)
+                  @timer = Wx::Timer.new(self, TIMER_ID)
+            
+                  evt_timer(TIMER_ID, :on_timer)
+            
+                  @timer.start(1000)    # 1 second interval
+                end
+                 
+                ...
+                 
+                def on_timer(event)
+                  # do whatever you want to do every second here
+                end
+              
+              end
+            ```

data/rakelib/lib/generate/doc/tool_bar.yaml

@@ -0,0 +1,35 @@
+---
+:wxToolBar.SetToolBitmapSize:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              toolbar.set_tool_bitmap_size(from_dip(Wx::Size.new(32, 32)))
+              toolbar.add_tool(Wx::ID_NEW, 'New', Wx::BitmapBundle.from_XXX(...))
+              ...
+              toolbar.realize
+            ```
+:wxToolBar:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /0\);/
+          :replace: |
+            
+            ```ruby
+              Wx::SystemOptions.set_option('msw.remap', 0)
+            ```
+        - :pattern: !ruby/regexp /2\);/
+          :replace: |
+            
+            ```ruby
+              Wx::SystemOptions.set_option('msw.remap', 2)
+            ```
+        - :pattern: !ruby/regexp /wxTheApp/
+          :replace: ''
+      :para:
+        - :pattern: !ruby/regexp /But\s+only\s+use.*true\s+colour:/
+          :subst: ''

data/rakelib/lib/generate/doc/top_level_window.yaml

@@ -0,0 +1,23 @@
+---
+:wxTopLevelWindow.MSWGetSystemMenu:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              if Wx::PLATFORM == 'WXMSW'
+            ```
+:wxTopLevelWindow.UseNativeDecorations:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              frame = MyFrame.new                   # use default ctor  
+              frame.use_native_decorations(false)   # change from default "true"
+              frame.create(parent, title, ...)      # really create the frame
+            ```

data/rakelib/lib/generate/doc/validator.yaml

@@ -0,0 +1,12 @@
+---
+:wxValidator.SetWindow:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              Wx::TextCtrl.new(self, Wx::ID_ANY, '', Wx::DEFAULT_POSITION, Wx::DEFAULT_SIZE, 0,
+                               Wx::TextValidator.new(Wx::FILTER_ALPHA))
+            ```

data/rakelib/lib/generate/doc/variant.yaml

@@ -0,0 +1,29 @@
+---
+:wxVariant:
+  :detail:
+    :pre:
+      :detaileddescription:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+
+            A variant's value can be changed at run time, possibly to a different type of value.
+            In wxRuby Wx::Variant is the only available Wx variant class (unlike in C++) and almost exclusively for
+            use in combination with the property grid classes (see the {Wx::PG} module).
+
+            By default Wx::Variant can store values of type bool, {Integer}, {Float}, {String}, {Time} (or {Date} / {DateTime}), {Array} of {String}, 
+            {Array} of {Wx::Variant}, {Wx::Font}, {Wx::Colour} and {Wx::ColourPropertyValue}.
+            In addition Wx::Variant can store any Ruby {Object}.
+            
+            An optional name member is associated with a Wx::Variant.
+            
+            In wxRuby Wx::Variant also provides the standard conversion methods #to_i, #to_s and #to_f for supported
+            value types. In case of incompatible value types these methods will raise a {TypeError} exception.
+:wxVariant.GetType:
+  :detail:
+    :post:
+      - :pattern: !ruby/regexp /\-\s+\"void\*\"$/
+        :subst: ''
+      - :pattern: !ruby/regexp /\Z/
+        :subst: |
+          
+          If the variant contains an arbitrary Ruby {Object}, the value type returned is the result of `variant.get_object.class.name`.

data/rakelib/lib/generate/doc/window.yaml

@@ -0,0 +1,249 @@
+---
+:wxWindow.SetScrollbar:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              set_scrollbar(Wx::VERTICAL, 0, 16, 50)
+            ```
+:wxWindow.FromDIP:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              bmp = Wx::Bitmap.new(from_dip(Wx::Size.new(32, 32)))
+            ```
+:wxWindow.ToDIP:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              pt = Wx::Point.new(to_dip(get_position))
+              size = Wx::Size.new(to_dip(get_size))
+            ```
+:wxWindow.SetMaxClientSize:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              set_max_size(client_to_window_size(size))
+            ```
+:wxWindow.SetMinClientSize:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              set_min_size(client_to_window_size(size))
+            ```
+:wxWindow.Move:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              set_size(x, y, Wx::DEFAULT_COORD, Wx::DEFAULT_COORD, Wx::SIZE_USE_EXISTING)
+            ```
+:wxWindow.ConvertDialogToPixels:
+  :detail:
+    :pre:
+      :para:
+        - :pattern: !ruby/regexp /A\s+convenience\s+macro\s+is\s+defined:/
+          :subst: ''
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: ''
+:wxWindow.SetBackgroundStyle:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              class MyWidget < Wx::Window
+                def initialize(parent, ...)
+                  super() # Use default ctor here!
+                   # Do this first:
+                   set_background_style(Wx::BG_STYLE_TRANSPARENT)
+            
+                   # And really create the window afterwards:
+                   create(parent, ...)
+                end
+              end
+            ```
+:wxWindow.HandleWindowEvent:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              get_event_handler.safely_process_event(event)
+            ```
+:wxWindow.ProcessWindowEvent:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              get_event_handler.process_event(event)
+            ```
+:wxWindow.PushEventHandler:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              W.push_event_handler(A)
+              W.push_event_handler(B)
+            ```
+:wxWindow.Enable:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              w = MyWindow.new # Note: default ctor is used here.
+              w.enable(false)
+              w.create(parent, ... all the usual non-default ctor arguments ...)
+            ```
+:wxWindow.EnableTouchEvents:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              enable_touch_events(Wx::TOUCH_ZOOM_GESTURE | Wx::TOUCH_ROTATE_GESTURE)
+            ```
+:wxWindow.DoUpdateWindowUI:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              # do the window-specific processing after processing the update event
+              def Wx::TopLevelWindow.do_update_window_ui(event)
+                if event.get_set_enabled
+                  enable(event.get_enabled)
+                end
+              
+                if event.get_set_text
+                  if event.get_text != get_title
+                    set_title(event.get_text)
+                  end
+                end
+              end
+            ```
+:wxWindow.UpdateWindowUI:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              class MyWindow
+                ...
+                def on_internal_idle
+                  update_window_ui(Wx::UPDATE_UI_FROMIDLE) if Wx::UpdateUIEvent.can_update(self)
+                end
+                ...
+              end
+            ```
+:wxWindow.Create:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /wxPanel/
+          :replace: |
+            
+            ```ruby
+              panel = Wx::Panel.new   # Note: default constructor used.
+              panel.hide  # Can be called before actually creating it.
+              panel.create(parent, Wx::ID_ANY, ...)   # Won't be shown yet.
+              ... create all the panel children ...
+              panel.show  # Now everything will be shown at once.
+            ```
+        - :pattern: !ruby/regexp /MyCreateWindowObjectFunction/
+          :replace: |
+            
+            ```ruby
+              # Suppose we have this function (which would typically be in a
+              # different file from the rest of the code).
+              def my_create_window_object_function
+                 MyCustomClassDerivingFromWindow.new
+              end
+              
+              # Then we can create a window of MyCustomClassDerivingFromWindow
+              # class without really knowing about this type, as we would have
+              # to do if we wanted to use the non-default constructor, like this:
+              
+              # First create the C++ object using the factory function.
+              window = my_create_window_object_function
+              
+              # And now create the underlying window.
+              #
+              # This should call the base Wx::Window#create.
+              # In C++ (wxWidgets) this method is not virtual and cannot be overloaded
+              # so the derived class can't customize this part.
+              # In wxRuby however this method can be overloaded as long as the following
+              # is kept in mind:
+              # 1. the overloaded version will **NOT** be called when using a non-default
+              #    constructor (Create will than be called from C++ which will always be 
+              #    the base Wx::Window version);
+              # 2. when calling the overloaded version from Ruby understand that the window
+              #    will not actually be created until after the `super` version has been called.
+              # In general it's best not to overload this method but to define a different method
+              # if a custom initializer is needed.
+              window.create(parent, Wx::ID_ANY, ...)
+            ```
+:wxWindow.MSWDisableComposited:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              class MyFrame < Wx::Frame
+                def initialize(...)
+                  ...
+                  p = Wx::Panel.new(self)
+                  if Wx::PLATFORM == 'WXMSW'
+                    p.msw_disable_composited
+                  end
+              
+                  # Using Wx::ClientDC will work now with this panel in wxMSW --
+                  # although it still won't with wxOSX nor wxGTK under Wayland.            
+                end
+                ...            
+              end
+            ```

data/rakelib/lib/generate/doc/wizard_page_simple.yaml

@@ -0,0 +1,14 @@
+---
+:wxWizardPageSimple.Chain:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              firstPage = FirstPage.new # derived from Wx::WizardPageSimple
+              firstPage.chain(SecondPage.new)
+                         .chain(ThirdPage.new)
+                         .chain(LastPage.new)
+            ```

data/rakelib/lib/generate/doc/xml_node.yaml

@@ -0,0 +1,7 @@
+---
+:wxXmlNode.GetNodeContent:
+  :detail:
+    :pre:
+      :para:
+        - :pattern: !ruby/regexp /tagnametagcontent\/tagname/
+          :subst: '<tagname>tagcontent</tagname>'

data/rakelib/lib/generate/doc/xml_resource.yaml

@@ -0,0 +1,27 @@
+---
+:wxXmlResource.Load:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              if !Wx::XmlResource.get.load('rc/*.xrc')
+                Wx.log_error("Couldn't load resources!")
+              end
+            ```
+:wxXmlResource.LoadDialog:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              dlg = MyDialog.new
+              Wx::XmlResource.get.load_dialog_subclass(dlg, main_frame, 'my_dialog')
+              dlg.show_modal
+            
+              dlg.destroy
+            ```

data/rakelib/lib/generate/doc.rb

@@ -1,6 +1,9 @@
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+
 ###
 # wxRuby3 wxWidgets interface generation templates
-# Copyright (c) M.J.N. Corino, The Netherlands
 ###
 
 require 'set'
@@ -277,6 +280,7 @@ module WXRuby3
 
       def _ident_str_to_doc(s, ref_scope = nil)
         return s if no_idents?
+        return s if %w[wxRuby wxMSW wxOSX wxGTK wxX11].any? { |w| s.start_with?(w) }
         nmlist = s.split('::')
         nm_str = nmlist.shift.to_s
         constnm = rb_wx_name(nm_str)
@@ -284,8 +288,12 @@ module WXRuby3
           if /(\w+)\s*\(([^\)]*)\)/ =~ nm_str   # method with arglist?
             fn = $1
             args = _arglist_to_doc($2)
-            mtdsig = args.empty? ? "#{rb_method_name(fn)}" : "#{rb_method_name(fn)}(#{args})"
             if ref_scope
+              mtdsig = if ref_scope == fn
+                         args.empty? ? 'initialize' : "initialize(#{args})"
+                       else
+                         args.empty? ? "#{rb_method_name(fn)}" : "#{rb_method_name(fn)}(#{args})"
+                       end
               sep = _is_static_method?(ref_scope, fn) ? '.' : '#'
               constnm = rb_wx_name(ref_scope)
               if DocGenerator.constants_xref_db.has_key?(constnm)
@@ -294,6 +302,7 @@ module WXRuby3
                 "Wx::#{constnm}#{sep}#{mtdsig}"
               end
             else
+              mtdsig = args.empty? ? "#{rb_method_name(fn)}" : "#{rb_method_name(fn)}(#{args})"
               [mtdsig, true]
             end
           else # constant or method name only
@@ -306,8 +315,12 @@ module WXRuby3
             elsif !_is_method?(nm_str, ref_scope)
               ["Wx::#{constnm}", true]
             else
-              mtdnm = rb_method_name(nm_str)
               if ref_scope
+                mtdnm = if ref_scope == nm_str
+                          'initialize'
+                        else
+                          rb_method_name(nm_str)
+                        end
                 sep = _is_static_method?(ref_scope, nm_str) ? '.' : '#'
                 constnm = rb_wx_name(ref_scope)
                 if DocGenerator.constants_xref_db.has_key?(constnm)
@@ -316,6 +329,7 @@ module WXRuby3
                   "Wx::#{constnm}#{sep}#{mtdnm}"
                 end
               else
+                mtdnm = rb_method_name(nm_str)
                 [mtdnm, true]
               end
             end
@@ -403,7 +417,7 @@ module WXRuby3
         itm_text = node_to_doc(node)
         # fix possible unwanted leading spaces resulting in verbatim blocks
         itm_text = itm_text.split("\n").collect {|s|s.lstrip}.join("\n") if itm_text.index("\n")
-        "- #{itm_text}"
+        "\n- #{itm_text}"
       end
 
       def node_to_doc(xmlnode)
@@ -571,6 +585,9 @@ module WXRuby3
             end
           end
         end
+        if @item_doc_ovr.has_key?(:replace)
+          doc = @item_doc_ovr[:replace][:text]
+        end
         doc.sub!(/\<b\>\{Wx::Perl.*/, '')
         doc.strip!
         # reduce triple(or more) newlines to max 2
@@ -589,6 +606,39 @@ module WXRuby3
         DocGenerator.constants_xref_db
       end
 
+      def type_to_doc(ctype_decl)
+        return ctype_decl if ctype_decl == 'void'
+        ctype = Typemap.strip_type_decl(ctype_decl)
+        nmlist = ctype.split('::')
+        nm_str = nmlist.shift.to_s
+        constnm = rb_wx_name(nm_str)
+        if nmlist.empty?  # unscoped id?
+          if DocGenerator.constants_xref_db.has_key?(constnm)
+            "#{DocGenerator.constants_xref_db[constnm]['mod']}::#{constnm}"
+          elsif DocGenerator.constants_xref_db.has_key?(rb_constant_name(nm_str))
+            "Wx::#{rb_constant_name(nm_str)}"
+          elsif DocGenerator.constants_xref_db.has_key?(rb_constant_name(nm_str, false))
+            "Wx::#{rb_constant_name(nm_str, false)}"
+          else
+            Typemap.wx_type_to_rb(ctype)
+          end
+        else
+          itmnm = nmlist.shift.to_s
+          if DocGenerator.constants_xref_db.has_key?(constnm)
+            constnm = "#{DocGenerator.constants_xref_db[constnm]['mod']}::#{constnm}"
+          elsif DocGenerator.constants_xref_db.has_key?(rb_constant_name(nm_str))
+            cnm = rb_constant_name(nm_str)
+            constnm = "#{DocGenerator.constants_xref_db[cnm]['mod']}::#{cnm}"
+          elsif DocGenerator.constants_xref_db.has_key?(rb_constant_name(nm_str, false))
+            cnm = rb_constant_name(nm_str, false)
+            constnm = "#{DocGenerator.constants_xref_db[cnm]['mod']}::#{cnm}"
+          elsif nm_str.start_with?('wx')
+            constnm = "Wx::#{constnm}"
+          end
+          "#{constnm}::#{rb_wx_name(itmnm)}"
+        end
+      end
+
     end
 
     def run