wxruby3 0.9.0.pre.rc.3 → 0.9.1

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

@@ -0,0 +1,188 @@
+---
+:wxPGProperty.OnCustomPaint.paintdata:
+  :brief:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: ''
+:wxPGProperty.DoGetValidator:
+  :detail:
+    :pre:
+      :detaileddescription:
+        - :pattern: !ruby/regexp /SetPropertyValidator/
+          :subst: '#set_property_validator'
+        - :pattern: !ruby/regexp /In.*most.*situations,.*first.*macro\)\:/
+          :subst: 'In most situations, code like this should work well:'
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              class MyPropertyClass < Wx::PG::IntProperty
+            
+            
+                class << self
+                  def validator
+                    @validator ||= MyValidator.new(...)
+                  end
+                end
+            
+                # ...
+            
+                def do_get_validator
+                  MyPropertyClass.validator
+                end
+            
+                # ...
+            
+              end
+            ```
+:wxPGProperty.ChildChanged:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              class MyProperty < Wx::PG::FlagsProperty
+            
+                def child_changed(thisValue, childIndex, childValue)
+                  # Acquire reference to actual type of data stored in variant
+                  flags = thisValue.object;
+                  case childIndex
+                    when 0
+                      flags.sub_prop1 = childValue.to_i
+                    when 1
+                      flags.sub_prop2 = childValue.to_s
+                    # ...
+                  end
+                  # return altered data
+                  Wx::Variant.new(flags)
+                end
+            
+              end
+            ```
+:wxPGProperty.ChangeFlag:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              enable(false)
+            ```
+:wxPGProperty.SetDefaultValue:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              set_attribute('DefaultValue', value)
+            ```
+:wxPGProperty.wxPGProperty:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              class WxPointProperty < Wx::PG::PGProperty
+            
+                def initialize(label = Wx::PG::PG_LABEL, name = Wx::PG::PG_LABEL, value = Wx::Point.new)
+                  super(label, name)
+            
+                  # should work in pretty much 100% of cases
+                  self.value = value
+            
+                  # add private child properties
+                  add_private_child( Wx::PG::IntProperty.new("X", Wx::PG::PG_LABEL,value.x))
+                  add_private_child( Wx::PG::IntProperty.new("Y", Wx::PG::PG_LABEL,value.y))
+                end
+            
+                # ...
+            
+              end
+            ```
+:wxPGProperty:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /class.*wxColourPropertyValue/
+          :replace: ''
+        - :pattern: !ruby/regexp /virtual.*ColourToString/
+          :replace: | 
+            
+            ```ruby
+              # Override in derived class to customize how colours are translated
+              # to strings.
+              def colour_to_string(col, index) end
+            
+              # Returns index of entry that triggers colour picker dialog
+              # (default is last).
+              def get_custom_colour_index; end
+            
+              # Helper function to show the colour dialog
+              def query_colour_from_user(variant) end
+
+              # Returns colour for given choice.
+              # Default function returns Wx::SystemSettings.get_colour(index).
+              def get_colour(index) end
+            ```
+        - :pattern: !ruby/regexp /WX_PG_DECLARE_VARIANT_DATA.*WX_PG_IMPLEMENT_VARIANT_DATA_DUMMY_EQ/m
+          :replace: ''
+        - :pattern: !ruby/regexp /class.*MyProperty.*:.*public.*wxPGProperty/
+          :replace: | 
+            
+            ``` ruby
+              class MyProperty < Wx::PG::PGProperty
+              
+                  # All arguments of this ctor must have a default value -
+                  # use Wx::PG::PG_LABEL for label and name
+                  def initialize(label = Wx::PG::PG_LABEL, name = Wx::PG::PG_LABEL, value = '')
+                    super(label, name)
+                    # self.value is Wx::Variant
+                    self.value = value
+                  end
+              
+                  def do_get_editor_class
+                    # Determines editor used by property.
+                    # You can replace 'TEXT_CTRL' below with any of these
+                    # builtin-in property editor identifiers: CHOICE, COMBO_BOX,
+                    # TEXT_CTRL_AND_BUTTON, CHOICE_AND_BUTTON, CHECK_BOX, SPIN_CTRL,
+                    # DATE_PICKER_CTRL.
+                    return Wx::PG::PG_EDITOR_TEXT_CTRL
+                  end
+              
+                  def value_to_string(value, argFlags)
+                    # TODO: Convert given property value to a string
+                  end
+              
+                  def string_to_value(variant, text, argFlags)
+                    # TODO: Adapt string to property value.
+                  end
+              
+              protected
+                  # ...
+              end
+            ```
+    :post:
+      - :pattern: !ruby/regexp /==\swxIntProperty.*==\swxUIntProperty/m
+        :subst: |
+          
+          == wxIntProperty
+          
+          It derives from {Wx::PG::NumericProperty} and displays value as a signed long integer.
+          Supported special attributes:
+           
+          - {Wx::PG::PG_ATTR_MIN}, {Wx::PG::PG_ATTR_MAX} to specify acceptable value range.
+          - {Wx::PG::PG_ATTR_SPINCTRL_STEP}, {Wx::PG::PG_ATTR_SPINCTRL_WRAP}, {Wx::PG::PG_ATTR_SPINCTRL_MOTION}: Sets SpinCtrl editor parameters. 
+          
+          == wxUIntProperty
+
+      - :pattern: !ruby/regexp /Since\s\{Wx::PG::PGProperty\}\sderives.*For\sinstance:/m
+        :subst: ''

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

@@ -0,0 +1,23 @@
+---
+:wxPropertyGrid.AddActionTrigger:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              propGrid.add_action_trigger(Wx::PG::PG_ACTION_NEXT_PROPERTY, Wx::K_RETURN)
+              propGrid.dedicate_key(Wx::K_RETURN)
+            ```
+:wxPropertyGrid.MakeColumnEditable:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              # see Wx::PG::PGProperty#change_flag
+              property.change_flag(Wx::PG::PG_PROP_READONLY, true)
+            ```

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

@@ -0,0 +1,30 @@
+---
+:wxPropertyGridInterface.Insert:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              # append category
+              my_cat_id = propertygrid.append(Wx::PG::PropertyCategory.new("My Category"))
+              
+              ...
+              
+              # insert into category - using second overload
+              my_item_id_1 = propertygrid.insert(my_cat_id, 0, Wx::PG::StringProperty.new("My String 1"))
+              
+              # insert before to first item - using first overload
+              my_item_id_2 = propertygrid.insert(my_item_id, Wx::PG::StringProperty.new("My String 2"))
+            ```
+:wxPropertyGridInterface.ReplaceProperty:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              pg.replace_property("Flags", Wx::PG::FlagsProperty.new("Flags", Wx::PG::PG_LABEL, newItems))
+            ```

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

@@ -0,0 +1,40 @@
+---
+:wxPropertyGridManager:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              pgMan = Wx::PG::PropertyGridManager.new(self, PGID,
+                  Wx::DEFAULT_POSITION, Wx::DEFAULT_SIZE,
+                  # These and other similar styles are automatically
+                  # passed to the embedded wxPropertyGrid.
+                  Wx::PG::PG_BOLD_MODIFIED|Wx::PG::PG_SPLITTER_AUTO_CENTER|
+                  # Include toolbar.
+                  Wx::PG::PG_TOOLBAR |
+                  # Include description box.
+                  Wx::PG::PG_DESCRIPTION |
+                  # Include compactor.
+                  Wx::PG::PG_COMPACTOR |
+                  # Plus defaults.
+                  wxPGMAN_DEFAULT_STYLE)
+              
+              page = pgMan.add_page("First Page")
+              
+              page.append(Wx::PG::PropertyCategory.new("Category A1"))
+              
+              page.append(Wx::PG::IntProperty.new("Number",Wx::PG::PG_LABEL,1))
+              
+              page.append(Wx::PG::ColourProperty.new("Colour",Wx::PG::PG_LABEL,Wx::WHITE))
+              
+              page = pgMan.add_page("Second Page")
+              
+              page.append(Wx::PG::StringProperty.new("Text", Wx::PG::PG_LABEL, "(no text)"))
+              
+              page.append(Wx::PG::FontProperty.new("Font",Wx::PG::PG_LABEL))
+              
+              # Display a header above the grid
+              pgMan.show_header
+            ```

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

@@ -0,0 +1,11 @@
+---
+:wxRichTextHTMLHandler.SetFontSizeMapping:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              html_handler.set_font_size_mapping([7,9,11,12,14,22,100])
+            ```

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

@@ -18,6 +18,14 @@
             
               end
             ```
+    :post:
+      - :pattern: !ruby/regexp /,\s+use\s+\{Wx::HAS_WINDOW_LABEL_IN_STATIC_BOX\}.*compile-time\./
+        :subst: '.'
+:wxStaticBox.Create:
+  :detail:
+    :post:
+      - :pattern: !ruby/regexp /,\s+use\s+\{Wx::HAS_WINDOW_LABEL_IN_STATIC_BOX\}.*compile-time\./
+        :subst: '.'
 :wxStaticBox.Enable:
   :detail:
     :pre:

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

@@ -0,0 +1,18 @@
+---
+:wxStyledTextCtrl.GetInsertionPoint:
+  :detail:
+    :pre:
+      :programlisting:
+        - :pattern: !ruby/regexp /.*/
+          :replace: |
+            
+            ```ruby
+              def get_current_char(tc)
+                pos = tc.insertion_point
+                if pos == tc.last_position
+                  nil
+                else
+                  tc.get_range(pos, pos + 1)
+                end
+              end
+            ```

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/xml_resource.yaml

@@ -11,6 +11,9 @@
                 Wx.log_error("Couldn't load resources!")
               end
             ```
+    :post:
+      - :pattern: !ruby/regexp /If\s+\{Wx::USE_FILESYS\}.*\)\./
+        :subst: 'If {Wx::Setup::USE_FILESYSTEM} is enabled, this method understands {Wx::FileSystem} URLs.'
 :wxXmlResource.LoadDialog:
   :detail:
     :pre:

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'
@@ -169,7 +172,7 @@ module WXRuby3
               end
             end
           end
-          text.gsub!(/WX(K_[A-Z]+)/) { "{Wx::#{$1}}"}
+          text.gsub!(/WX(K_[A-Z]+)/) { "{Wx::KeyCode::#{$1}}"}
         end
         if event_section?
           case text
@@ -277,7 +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) }
+        return s if %w[wxRuby wxMSW wxOSX wxGTK wxX11 wxMac].any? { |w| s.start_with?(w) }
         nmlist = s.split('::')
         nm_str = nmlist.shift.to_s
         constnm = rb_wx_name(nm_str)
@@ -285,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)
@@ -295,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
@@ -307,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)
@@ -317,6 +329,7 @@ module WXRuby3
                   "Wx::#{constnm}#{sep}#{mtdnm}"
                 end
               else
+                mtdnm = rb_method_name(nm_str)
                 [mtdnm, true]
               end
             end
@@ -330,6 +343,7 @@ module WXRuby3
             mtd = $1
             args = _arglist_to_doc($2)
           end
+          # transform the scope prefix
           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))
@@ -342,8 +356,18 @@ module WXRuby3
             known = false
             constnm = "Wx::#{constnm}"
           end
+          # transform and append the element id
           if mtd.nil?
-            if DocGenerator.constants_xref_db.has_key?(rb_wx_name(itmnm)) || !_is_method?(itmnm, nm_str)
+            if DocGenerator.constants_xref_db.has_key?(rb_wx_name(itmnm))
+              itmnm = rb_wx_name(itmnm)
+              # in case of enum constants the documented scope most likely omits the enum class
+              # which we want for correct linking for wxRuby
+              if DocGenerator.constants_xref_db[itmnm]['mod'].start_with?("#{constnm}::")
+                ["#{DocGenerator.constants_xref_db[itmnm]['mod']}::#{rb_wx_name(itmnm)}", known]
+              else
+                ["#{constnm}::#{rb_wx_name(itmnm)}", known]
+              end
+            elsif !_is_method?(itmnm, nm_str)
               ["#{constnm}::#{rb_wx_name(itmnm)}", known]
             else
               sep = _is_static_method?(nm_str, itmnm) ? '.' : '#'
@@ -572,6 +596,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